home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-01
/
cwl2f-3.zip
/
MANUAL.DOC
< prev
next >
Wrap
Text File
|
1992-04-26
|
709KB
|
21,707 lines
@ME.FORMAT R
THE C WINDOW LIBRARY
(c) Copyright P. A. McKenzie 1990, 1991, 1992
All Rights Reserved
Version 2.0e
T A B L E O F C O N T E N T S
PRELIMINARIES ......................................... i
Microsoft C ........................................ i
Turbo C/C++/Borland C++ ............................ ii
Power C ............................................ ii
Zortech C++ ........................................ iii
INTRODUCTION ........................................... 1
Defining Windows .................................... 1
Properties of Windows ............................... 1
Writing to Overlapping Windows ...................... 2
Window Ranks ........................................ 2
Detection of Video Hardware ......................... 2
Window Coordinates .................................. 2
Video Attributes .................................... 3
Direct Screen Writes and BIOS Screen Updates ........ 4
Video Paging ........................................ 5
Error Codes ......................................... 6
Window Manager ...................................... 8
MANDATORY FUNCTIONS AND HEADER FILES ................... 9
WindowInitializeSystem() ............................ 9
CREATING WINDOWS ....................................... 10
The WINDOW structure and WPOINTER structure pointer . 10
WindowSaveInitial() ................................. 10
WindowInitialize() .................................. 11
CREATE_VIDEO_ATTRIBUTE() macro ...................... 12
Box types ........................................... 12
OPENING WINDOWS FOR READING AND WRITING ................ 15
WindowOpen() ........................................ 15
DISPLAYING WINDOWS ..................................... 16
The WindowDisplay() function and Explosion Effects .. 16
Displaying Multiple Windows ......................... 19
CLOSING WINDOWS ........................................ 21
WindowClose() ....................................... 21
WindowFree() ........................................ 22
WindowCloseAll() .................................... 23
WindowFreeAll() ..................................... 24
CENTERING WINDOWS ON THE SCREEN ........................ 25
WindowCenter() ...................................... 25
The C Window Library
CHANGING WINDOW CHARACTERISTICS ........................ 27
WindowChangeTextAttribute() ......................... 27
WindowChangeBorderAttribute() ....................... 28
WindowDrawBorder() .................................. 28
WindowRemoveBorder() ................................ 30
WindowResizeHeight() ................................ 30
WindowResizeWidth() ................................. 31
WRITING TEXT TO WINDOWS ................................ 33
Null Terminated Write Functions ..................... 33
WindowWriteString() .............................. 33
WindowWriteStringAttr() .......................... 34
WindowWriteCenterString() ........................ 35
WindowWriteCenterStringAttr() .................... 36
WindowWriteStringCC() ............................ 36
WindowWriteStringCCAttr() ........................ 37
WindowWriteStringRJ() ............................ 38
WindowWriteStringRJAttr() ........................ 39
Length Controlled Write Functions.................... 40
WindowWriteCharacters() .......................... 40
WindowWriteAttributes() .......................... 41
WindowWriteCharAndAttr() ......................... 42
WindowWriteCharactersAttr() ...................... 43
WindowWriteRepeatAttribute() ..................... 44
WindowWriteRepeatCharacter() ..................... 45
Formatted Write Functions ........................... 46
Where output is placed in the window ............. 46
WindowSetWrap() .................................. 46
WindowPrintf() ................................... 47
WindowPrintfAttr() ............................... 48
WRITING TITLES TO WINDOWS .............................. 50
WindowTitleTop() .................................... 51
WindowTitleBottom() ................................. 52
WindowTitleTopAttr() ................................ 53
WindowTitleBottomAttr() ............................. 54
READING CHARACTERS AND ATTRIBUTES FROM WINDOWS ......... 56
WindowReadCharacters() .............................. 56
WindowReadAttributes() .............................. 57
WindowReadCharAndAttr() ............................. 58
HIDING WINDOWS ......................................... 60
WindowHide() ........................................ 60
CREATING COPIES OF A WINDOW ............................ 62
WindowCopy() ........................................ 62
The C Window Library
SCROLLING TEXT IN WINDOWS .............................. 64
WindowScroll() ...................................... 64
WindowScrollRegion() ................................ 65
WindowScrollAttr() .................................. 66
WindowScrollRegionAttr() ............................ 67
CLEARING WINDOWS ....................................... 69
WindowClear() ....................................... 69
WindowClearAttr() ................................... 70
WindowClearRegion() ................................. 70
WindowClearRegionAttr() ............................. 71
WRITING WINDOW CONTENTS TO A FILE ...................... 73
WindowWriteTextToFile() ............................. 73
SHADOWING WINDOWS ...................................... 75
WindowDrawShadow() .................................. 75
WindowRemoveShadow() ................................ 77
SEE-THRU WINDOWS ....................................... 78
WindowMakeSeeThru() ................................. 78
WindowMakeNormal() .................................. 79
MOVING AND SLIDING WINDOWS ............................. 80
WindowMove() ........................................ 80
WindowSlide() ....................................... 81
CURSOR POSITIONING IN WINDOWS .......................... 82
Cursor Maintenance in The C Window Library .......... 82
Creating Cursor Shapes .............................. 82
WindowChangeCursor() ................................ 82
WindowMoveCursor() .................................. 83
WindowGetCursorShape() .............................. 84
WindowGetCursorPosition() ........................... 85
GETTING WHICH WINDOW OCCUPIES A LOCATION ............... 87
WindowWhich() ....................................... 87
GETTING INPUT FROM WINDOWS ............................. 88
Input Manager ....................................... 88
Regular Expressions ................................. 88
Editing Input ....................................... 93
Last Key Value ...................................... 95
Default Cursor Types and Editing Mode ............... 96
Editing using a character mask ...................... 97
The C Window Library
Editing Functions ................................... 97
WindowGetString() ................................ 97
WindowGetStringAttr() ............................ 99
WindowGetMaskString() ............................ 100
WindowGetMaskStringAttr() ........................ 102
Getting Passwords ................................ 103
WindowGetPassword() ........................... 103
WindowGetPasswordAttr() ....................... 104
WindowGetMaskPassword() ....................... 105
WindowGetMaskPasswordAttr() ....................106
Undefined Keystroke Processing ................... 107
The undef_fkey_func and undef_akey_func
function pointers ................. 107
Specifying when to call an undefined key
function in a Regular Expression ...... 108
Return Values To The Input Manager .......... 109
Input Options .................................... 112
CHECKREGEXP and the reg_exp_error_func
function pointer ........................... 113
THE num_chars_entered_func FUNCTION POINTER ...... 116
Other Input releated functions ................... 117
TranslateStringToMaskString() .................... 117
TranslateMaskStringToString() .................... 119
VIRTUAL WINDOWS ........................................ 121
Using Windows as Viewports .......................... 121
Attributed and Non-Attributed Virtual Windows ....... 121
Virtual Window's Logical Cursor ..................... 122
CREATING VIRTUAL WINDOWS ............................ 123
VirtualInitialize() .............................. 123
ASSIGNING VIEWPORTS AND CLOSING VIEWPORTS ........... 125
WindowAssignToVirtual() .......................... 125
Out of bounds Coordinates ........................ 126
WindowCloseViewport() ............................ 127
WRITING TEXT TO VIRTUAL WINDOWS ..................... 129
Null Terminated String Functions ................. 129
VirtualWriteString() .......................... 129
VirtualWriteStringAttr() ...................... 130
VirtualWriteCenterString() .................... 131
VirtualWriteCenterStringAttr() ................ 132
VirtualWriteStringCC() ........................ 133
VirtualWriteStringCCAttr() .................... 134
VirtualWriteStringRJ() ........................ 135
VirtualWriteStringRJAttr() .................... 136
The C Window Library
Length Controlled Functions ...................... 137
VirtualWriteCharacters() ...................... 137
VirtualWriteAttributes() ...................... 138
VirtualWriteCharAndAttr() ..................... 139
VirtualWriteRepeatAttribute() ................. 140
VirtualWriteRepeatCharacter() ................. 141
Formatted Write Functions ........................ 142
Format String ................................. 142
Where Output is Placed ........................ 142
VirtualSetWrap() .............................. 142
VirtualPrintf() ............................... 143
VirtualPrintfAttr() ........................... 144
READING CHARACTERS AND ATTRIBUTES FROM
VIRTUAL WINDOWS .............. 146
VirtualReadCharacters() .......................... 146
VirtualReadAttributes() .......................... 147
VirtualReadCharAndAttr() ......................... 148
REPOSITIONING THE VIEWPORT .......................... 150
WindowPositionViewport() ......................... 150
SCROLLING THE VIEWPORTS ............................. 154
WindowScrollVirtual() ............................ 154
WRITING VIRTUAL WINDOW CONTENTS TO A FILE ........... 157
VirtualWriteTextToFile() ......................... 157
MOVING THE LOGICAL CURSOR ........................... 159
VirtualMoveCursor() .............................. 159
VirtualGetCursorPosition() ....................... 159
CLEARING VIRTUAL WINDOWS ............................ 161
VirtualClear() ................................... 161
VirtualClearAttr() ............................... 162
VirtualClearRegion() ............................. 162
VirtualClearRegionAttr() ......................... 163
FREEZING VIEWPORTS .................................. 165
WindowFreeze() ................................... 165
DISPOSING OF VIRTUAL WINDOWS ........................ 167
VirtualFree() .................................... 167
The C Window Library
INTRODUCTION TO MENU SYSTEM ............................ 169
Menu Manager ........................................ 169
Necessary "include" files ........................... 169
POP-UP MENUS ........................................ 170
Description ...................................... 170
Windows and Virtual Windows ...................... 170
CREATING POP-UP MENUS ............................... 171
The POPUP_MENU_ENTRY structure ................... 171
Defining Hotkeys .............................. 172
Assigning the function to perform ............. 173
Coloring Popup Menus ............................. 173
Creating Popup Menu Entries Dynamically .......... 174
PopupCreateMenu() function ....................... 179
Popup Menu Options ............................ 180
Default Popup Window and Creating
Your own Windows ............. 182
Default Virtual Window and
Creating Your own Virtual Windows ....... 184
Accessing Popup Windows and Virtual Windows ... 184
Warnings ...................................... 185
Return Values for PopupCreateMenu() ........... 185
SELECTING FROM POPUP MENUS .......................... 187
PopupSelectMenu() function ....................... 187
Values passed to menu function ................ 189
Values returned to menu manager ............... 189
Return Values for PopupSelectMenu() ........... 190
SETTING OPTIONS IN POPUP MENUS ...................... 191
The PopupSetOptions() function ................... 191
Setting Multiple Options ...................... 192
Setting the PopupSetConfirmFunction() ......... 192
Return Values for PopupSetOptions() function .. 193
MAKING MENU ENTRIES AVAILABLE AND UNAVAILABLE ....... 194
PopupMakeEntryAvailable() and
PopupMakeEntryUnavailable() functions ............ 194
POPUPOVERRIDE option .......................... 194
Return Values for PopupMakeEntryAvaialble() and
PopupMakeEntryUnavailable() functions ............ 194
CHANGING THE MENU ENTRY STRINGS ..................... 196
PopupChangeEntryString() function ................ 196
Return Values for PopupChangeEntryString()
function ................ 196
The C Window Library
REDEFINING MENU KEYS ................................ 197
Setting Global Key Definitions and
the popup_key_definition Array ............ 197
Setting Local Key Definitions .................... 197
PopupAssignKeys() function .................... 198
Return Values for PopupAssignKeys() function .. 198
PROCESSING UNDEFINED KEYS ........................... 199
The popup_undef_key function pointer ............. 199
Values returned to menu manager ............... 199
PRE-INPUT FUNCTION .................................. 203
Setting the global_popup_prefunc
function pointer .............. 203
DISPOSING OF POPUP MENUS ............................ 205
PopupMenuFree() .................................. 205
Return Values for PopupMenuFree() ................ 205
BAR MENUS .............................................. 206
Description ......................................... 206
Windows and Virtual Windows ......................... 206
CREATING BAR MENUS .................................. 207
The BAR_MENU_ENTRY structure ..................... 207
Defining Hotkeys .............................. 208
Assigning the function to perform ............. 209
Coloring Bar Menus ............................... 209
Creating Bar Menu Entries Dynamically ............ 210
BarCreateMenu() function ......................... 214
Bar Menu Options .............................. 215
Default Bar Menu Window and Creating
Your own Windows .......... 217
Accessing bar menu windows .................... 219
Warnings ...................................... 219
Return Values for BarCreateMenu() ............. 219
SELECTING FROM BAR MENUS ............................ 221
BarSelectMenu() function ......................... 221
Values passed to menu function ................ 223
Values returned to menu manager ............... 223
Return Values for BarSelectMenu() ............. 223
SETTING OPTIONS IN BAR MENUS ........................ 225
The BarSetOptions() function ..................... 225
Setting Multiple Options ...................... 226
Setting the BarSetConfirmFunction() ........... 226
Return Values for BarSetOptions() function .... 227
The C Window Library
MAKING ENTRIES AVAILABLE AND UNAVAILABLE ............ 228
BarMakeEntryAvailable() and
BarMakeEntryUnavailable() functions .............. 228
BAROVERRIDE option ............................ 228
Return Values for BarMakeEntryAvaialble() and
BarMakeEntryUnavailable() functions .............. 228
CHANGING THE MENU OPTIONS STRING .................... 230
BarChangeEntryString() function .................. 230
Return Values for BarChangeEntryString()
function ...................................... 230
REDEFINING THE MENU KEYS ............................ 232
Setting Global Key Definitions and
the bar_key_definition Array ............... 232
Setting Local Key Definitions .................... 232
BarAssignKeys() function ...................... 232
Return Values for BarAssignKeys() function .... 233
PROCESSING UNDEFINED KEYS ........................... 234
The bar_undef_key function pointer ............... 234
Values returned to menu manager ............... 234
PRE-INPUT FUNCTION .................................. 237
Setting the global_bar_prefunc function pointer... 237
DISPOSING OF BAR MENUS .............................. 239
BarMenuFree() function ........................... 239
Return Values for BarMenuFree() .................. 239
PULLDOWN MENUS ......................................... 240
Description ......................................... 240
Bar Menu and Popup Menu levels ...................... 240
CREATING PULLDOWN MENUS ............................. 241
The PulldownCreateMenu() function ................ 242
Automatic Adjustment of Popup Windows ......... 244
Return values for PulldownCreateMenu() ........... 247
SELECTING FROM PULLDOWN MENUS ....................... 248
The PulldownSelectMenu() function ................ 248
Immediate Mode ................................ 248
Values passed to the selected menu function ... 249
Values returned to the menu manager ........... 249
Return Values for PulldownSelectMenu() ........ 249
The C Window Library
REDEFINING KEY DEFINITIONS .......................... 250
REDEFINING KEY DEFINITIONS FOR POPUP MENUS ....... 251
Setting Popup Menu Global Key Definitions ..... 251
Setting Popup Menu Local Definitions .......... 252
REDEFINING KEY DEFINITIONS FOR THE BAR MENU ...... 253
Setting bar menu global key definitions ....... 253
Setting Bar Menu Local definitions ............ 253
PROCESSING UNDEFINED POPUP MENU KEYS ................ 254
PROCESSING UNDEFINED BAR MENU KEYS .................. 255
DISPOSING OF PULLDOWN MENUS ......................... 256
The PulldownMenuFree() function .................. 256
The PulldownMenuFreeAll() function ............... 256
SUMMARY OF PULLDOWN MENUS ........................... 257
EXAMPLE OF PULLDOWN MENU SYSTEM ..................... 258
MISCELLANEOUS FUNCTIONS ................................ 262
SETTING AND CHECKING VIDEO PAGES .................... 262
CheckVideoPage() ................................. 262
SetActiveVideoPage() function .................... 263
SetVisibleVideoPage() function ................... 264
GENERAL STRING WRITING FUNCTIONS .................... 266
VideoWriteString() ............................... 266
VideoWriteStringAttr() ........................... 267
VideoWriteAttributes() ........................... 267
VideoWriteCenterString() ......................... 268
VideoWriteCenterStringAttr() ..................... 269
VideoWriteCharAndAttr() .......................... 269
VideoWriteStringCC() ............................. 270
VideoWriteStringCCAttr() ......................... 271
VideoWriteStringRJ() ............................. 271
VideoWriteStringRJAttr() ......................... 272
VideoPrintf() .................................... 273
VideoPrintfAttr() ................................ 273
The C Window Library
READING CHARACTERS AND ATTRIBUTES FROM THE SCREEN ... 275
VideoReadCharacters() ............................ 275
VideoReadAttributes() ............................ 275
VideoReadCharAndAttr() ........................... 276
DRAWING BOXES ....................................... 277
VideoDrawBox() ................................... 277
VideoDrawBoxAttr() ............................... 277
SAVING AND RESTORING SCREEN IMAGES .................. 279
VideoSave() ...................................... 279
VideoMove() ...................................... 280
VideoRestore() ................................... 280
VideoFree() ...................................... 281
CLEARING SCREENS .................................... 282
ClearScreen() .................................... 282
ClearRegion() .................................... 282
SCROLLING SCREENS ................................... 284
ScrollScreenUp() ................................. 284
ScrollScreenDown() ................................284
CHANGING THE VIDEO MODE ............................. 286
SetVideoMode() ................................... 286
CHANGING THE NUMBER OF ROWS AND COLUMNS ON
THE SCREEN .............. 287
Changing rows .................................... 287
AdjustScreenInfo() ............................ 287
AdjustGlobalData() ............................ 288
SetVideoRows() ................................ 288
Changing columns ................................. 291
40 column and 80 column modes ................. 291
Modes higher than 80 columns .................. 292
CURSOR MANIPULATION ................................. 294
MoveCursor() ..................................... 294
ChangeCursor() ................................... 294
GetCursorShape() ................................. 295
GetCursorPosition() .............................. 295
HideCursor() ..................................... 296
BlockCursor() .................................... 296
ThinCursor() ..................................... 296
The C Window Library
GETTING VIDEO INFORMATION ........................... 298
VIDEO_CONFIG structure ........................... 298
GetVideoBiosInfo() ............................... 298
TIMED DELAYS ........................................ 300
delay() .......................................... 300
SOUND FUNCTIONS ..................................... 301
sound() and nosound() ............................ 301
MakeSound() ...................................... 301
ERROR HANDLING ...................................... 303
The window_error_func function pointer ........... 303
USING A MOUSE WITH THE C WINDOW LIBRARY ............. 306
Installing the Mouse Library ..................... 306
Include Files .................................... 306
Initializing the Mouse with
MouseInitializeSystem().......... 306
Turning off the mouse with MouseRestoreSystem() .. 307
Using a mouse with popup menus ................... 308
Popup Menu's prefunction for mouse ........... 310
Using a mouse with bar menus ..................... 311
Using a mouse with pulldown menus ................ 313
Changing the mouse defaults ...................... 314
WINDOW AND VIRTUAL WINDOW MACROS .................... 315
MENU MACROS ......................................... 318
Popup Menu Macros ................................ 318
Bar Menu Macros .................................. 320
Pulldown Menu Macros ............................. 321
VIDEO MACROS ........................................ 322
BOX MACROS .......................................... 326
EXPLOSION MACROS .................................... 327
KEYBOARD MACROS ..................................... 328
Keyboard Idle Function ............................ 329
Keyboard Intercept Function ....................... 330
Checking for mouse presses ........................ 331
CURSOR MACROS ....................................... 333
IMPORTANT GLOBAL VARIABLES ............................. 334
The C Window Library
PRELIMINARIES
-------------
Congratulations on using The C Window Library; the easiest to
use, most powerful, inexpensive C user interface library!
Before we start talking 'C', we will discuss briefly on how
to compile and link programs using The C Window Library.
The following discussion is very brief. For more in depth
information on make files, project files, link options, etc.
please consult the various documentation supplied with the
compiler that you are working with.
The default word/byte alignment scheme was used when
compiling all the libraries. In other words, all modules
used by The C Window Library were compiled without the use of
the word/byte alignment switch being used.
Microsoft / Quick C
-------------------
When compiling your programs, you must make sure that the
constant MSC is defined. An example of how you would do this
as follows:
cl -Ax -DMSC -Ihfiles prog1.c /link mswinx.lib msmousex.lib
the -Ax is the model used for compilation. The x stands for
either S for small, M for medium, C for compact, or L for
large. The -D option defines a constant, which in this case
is MSC. You must use the -D switch with MSC as the constant.
If not, you will get either syntax errors, link errors, or
runtime errors. The -I option tells the compiler that the .h
files are located in a directory on the default drive called
hfiles. The /link option links the resulting object files
(prog1.obj) with The C Window Library file mswinx.lib, where
x stands for S, M, C, or L. The mouse library msmousex.lib,
where x stands for S, M, C, or L, is necessary only if you
plan to use the mouse in your application.
The other method is to create a make file. If you are using
the integrated environment of Quick C or using the
Programmers Work Bench (PWB) for Microsoft C 6.0, you can
create your make files by selecting the files you want to
compile, and the libraries you want to link with and letting
these integrated environments create the make file
automatically. If you are more advanced you can create your
make files by yourself without the aid of these programs.
Consult the documentation for more information on make files.
i
Turbo C/TurboC++/Borland C++
----------------------------
If you will use the integrated environment, you must create a
project file. This project file specifies the source code
modules, object code modules, and libraries that will be
linked in to produce an executable file. If you use the
Turbo C Version 2.0 integrated environment, you must edit
this file yourself. If you use the Turbo C++ or Borland C++
integrated environment, use the automatic Project File
creator.
You can also use make files to link in your program. Make
sure that the desired library from The C Window Library is
specified.
You can also use the TCC.EXE (or BCC if you are using
Borland C++) command line compiler with the desired library
specified on the command line. Consult the Turbo C/C++
documentation on using make files and using the integrated
environment.
The default structure alignment was used to compile the
libraries, which is byte alignment.
An example of using the TCC.EXE (BCC.EXE) command line is as
follows:
tcc -mm -G -r -ihfiles prog1.c tcwinm.lib tcmousem.lib
The following command line uses -mm for the medium memory
model, -G to optimize for speed, -r for usage of register
variables, and -i to tell the compiler that the header files
are located in a directory on the default drive called
hfiles. The mouse library, tcmousem.lib, is necessary only
if you plan to use the mouse in your application.
Power C
-------
If you are using the POWER C compiler from Mix Software, you
must define the constant POWERC on the command line.
pc -dPOWERC -mm -ihfiles prog1.c
You must have the constant POWERC defined on the pc.exe
command line using the -d option. If not, you may get
syntax, link, or runtime errors. The -mm tells the compiler
to use the medium memory model, and the -i option tells the
compiler that there are .h files located on the default drive
in the directory hfiles.
Depending on the number of windows your application will use
and the code size, you will have to use different stack and
heap options in the Power C linker, pcl. An example of this
is as follows:
ii
pcl [20k,30k,200k] a;pcwinm;pcmousem
This will link the object file a.mix with the pcwinm.mix
library with 20k of stack space, 30k of near heap space, and
200k of far heap space. If your application has many or very
large virtual windows, you should use the maximum far heap
space allowable. If your program has many windows, you
should increase the near heap space parameter, or use the
pcwinl.mix library and increase the far heap space parameter.
If your program has recursive or deeply nested functions, you
should increase the stack parameter. However the stack and
near heap space cannot exceed 64k. This includes global and
static declarations in the program. The mouse library,
pcmousex, is necessary only if you plan to use the mouse in
your application.
Zortech C++
-----------
If you are using the Zortech C++ compiler, you should use
the following options when compiling your program with The C
Window Library:
ztc -o -b -p -mm prog1.c zcwinm.lib zcmousem.lib
The -o option turns on the global optimizer. The -b option
lets ztc know to handle large programs. The -p turns off
auto-prototyping. The -mm option lets the compiler use the
medium memory model. The programs prog1.c is compiled using
these options and then linked with the medium memory model of
The C Window Library's Zortech version, namely zcwinm.lib.
The mouse library, zcmousem.lib, is necessary only if you
plan to use the mouse in your application.
iii
INTRODUCTION
------------
Defining Windows
----------------
A window is an area of the screen that is separate and
independent from the other areas of the screen. With
windows, you can scroll, write text, delete text, etc. in a
defined section of the screen. An example of windows in
application programs are the resident memory utilities that
pop up on the screen when invoked, and restore the text to
its original state when the resident application is
terminated. Sidekick is a good example of what you can do
with windows. As a matter of fact, most professional
programs use windows in some manner. Some applications use
windows to make pulldown menus i.e. the integrated
environment in the Turbo languages and in Microsoft Quick
C's integrated environment. Other applications such as text
editors and word processors use windows to display and edit
a files contents. With The C Window Library, you can create
professional looking application program easily and without
worrying about the tricky details of window management. At
your disposal are tools that can help you create pull-down
menus, popup menus, bar menus, and just fast output.
Properties of Windows
---------------------
Windows should have the following properties:
- more than one window can be displayed on the screen
simultaneously.
- windows are allowed to overlap without disturbing the
contents of the windows underneath.
- a window that is under a pile of windows can be brought
to the top.
- a window that is under a pile of windows can be written
to without interfering with other windows.
- windows can be disposed of when not needed, and erased
from the screen. When erased, the contents of the
screen underneath the window is restored.
- windows can be written to at any time.
- the window application should automatically detect the
type of video hardware used.
- the window functions should return an error if something
goes wrong.
Page 1 The C Window Library Page 1
Writing to Overlapping Windows
------------------------------
With The C Window Library, if a window does overlap another
window, this overlap will be displayed on the physical
screen. The C Window Library allows you to direct output to
any window at any time. When output is written to a window,
the window contents are updated in memory, but only the
visible portions of the window will be updated on the screen.
Window Ranks
------------
The rank order of the windows on the screen will determine
which window has priority of the screen.
Windows with lower rank numbers overlap windows with higher
rank numbers. The lowest rank number is 1, and the highest
is 254. If a new window is opened with the same rank number
as another previously opened window, the new window takes
over the rank position, and the previous window's rank is
increased by 1. If there is a window with the same rank as
the previous window's new rank, its rank is increased by 1
etc. When a window is closed, all windows with a higher
rank number are decreased by 1.
Detection of Video Hardware
---------------------------
With The C Window Library, automatic detection of the type
of video hardware is necessary. Since The C Window Library
can write directly to screen memory, the starting memory
address of screen memory must be known. Depending on the
video adapter, the starting address of screen memory is
different. For monochrome systems, the starting address is
different from a color system. If the window routines think
that they are writing to a color system instead of a
monochrome system, crazy things will probably happen. For
most adapters, The C Window Library will detect them and
assign the starting address of screen memory to a global
variable, so there is no need to specify the starting
address yourself.
Window Coordinates
------------------
A position on the screen can be specified as a pair of
numbers. These numbers will denote the row and column of
the desired position. Rows and columns are numbered from 1
to the maximum row or column number. The upper left hand
corner of the screen would be at row 1, column 1. For
Page 2 The C Window Library Page 2
simplicity, row y, column x will be abbreviated as (y,x).
The position (1,1) is called the home position.
However, when specifying a position in a window, this
position is numbered relative to the window itself. No
matter where a window resides on the screen, the upper left
position of the window is (1,1), the second row of the
window is row 2, the fourth column is column 4, etc. The
window coordinates are called window relative coordinates.
There are some window functions that require you to enter
physical screen (absolute) coordinates, but for most
functions, a window relative position would be needed. For
example:
-----------------------------------------------------------
|(1,1) (80,1)|
| |
| Valid Absolute Screen Coordinates |
| For 80 x 25 Screen |
| |
| This window opened at absolute (12,15) |
| | |
| v |
| ----------------------- |
| |(1,1) (1,30)| |
| | | |
| | | |
| |(14,1) (14,30)| |
| ----------------------- |
|(1,25) (80,25)|
-----------------------------------------------------------
Video Attributes
----------------
With The C Window Library, a window can have an assortment
of colors for text and background. Each character that is
displayed on the screen has its corresponding attribute
byte. The attribute byte is an 8-bit quantity that
specifies a character's color, intensity, and blink status.
The format of the attribute byte is as follows:
7 6 5 4 3 2 1 0
--------------------------
|B | bground |I|fground |
|__|_________|_|_________|
The B is the blink bit and the I is the intensity bit. Bits
0 thru 2 is a color code for the foreground (text) color.
Bits 4 thru 6 determine the color code for the background
(screen) color.
Page 3 The C Window Library Page 3
If the blink bit is 1, then the character will blink. If
the intensity bit is on, the character will appear brighter
than usual. Some monitors cannot display high intensity
characters, so the intensity bit may not change the
characters brightness at all.
Here is a list of color values along with the color
they represent:
Value Color Value Color
0 Black 8 Gray
1 Blue 9 Light blue
2 Green 10 Light green
3 Cyan 11 Light cyan
4 Red 12 Light red
5 Magenta 13 Light magenta
6 Brown 14 Yellow
7 White 15 Intense white
If the video system is a monochrome system, the color values
specified above will give unpredictable results if not used
carefully. Monochrome systems also have an underline mode,
that color systems (unless if you program the EGA or VGA
adapters) cannot display. Upcoming is a list of color
values that should work on monochrome systems along with the
type of display that will be produced:
Display Background Foreground
No display 0 0
Underline 0 1
Normal Video 0 7
Reverse Video 7 0
When programming a monochrome system, you can change the
values of the colors not supported to black and white
combinations supported on the monochrome system. For
example, you can change the light green color's value from
10 to 7. Now if light green is selected as a foreground
color and the background color is black, you will have a
normal video display on a monochrome system.
Direct Screen Writes and BIOS Screen Updates
--------------------------------------------
By default, The C Window Library writes directly to screen
memory. This results in very fast screen output. If you
have ever wondered how commercial programs can display
output so rapidly on the screen, direct screen writing is
Page 4 The C Window Library Page 4
the major reason. The disadvantage of writing directly to
the screen is that it is ill- behaved with programs like
Microsoft Windows or Quarterdeck's DesQView (although
DesQView386 running on an 80386 machine is well behaved with
direct screen writes). Also on some color systems, the
screen output is so fast that the video display produces
"snow" on the screen. However, The C Window Library will
automatically detect whether "snow" should be checked when
writing directly to the screen. The old IBM Color Graphics
Adapters suffer from this problem, but most other adapters
including monochrome, Hercules, EGA, VGA, and newer CGA's do
not suffer from this problem. When checking for snow, the
screen writes are not as fast as when there is no snow
checking, but it is fast enough.
The other method of updating the screen is by making a call
to the video functions contained in the ROM BIOS. BIOS
stands for Basic Input Output System. The BIOS provides
routines that are needed for the operation of the computer.
Some of these routines are video functions needed to write
characters and attributes, move the cursor, and scroll
portions of the screen. Using the BIOS instead of writing
directly to screen memory results in much slower screen
updates, but will be compatible with programs like Microsoft
Windows and DesQView.
With The C Window Library, you are allowed to use either
method.
Video Paging
------------
Since most video display adapters have enough memory to
store more than one screen of characters, these video
adapters will support multiple video pages. With multiple
video pages, you can write to a hidden video page and then
display the entire video page instantaneously. The only
adapter that does not support video paging is the Monochrome
Display Adapter (MDA). All CGA's, EGA's and VGA's support
multiple video pages. The maximum number of pages a card
will support is determined by the amount of RAM included in
the video board, and the maximum number of characters that
can be displayed on each page. A list of the maximum number
of video pages in each mode for each card is as follows:
Page 5 The C Window Library Page 5
BIOS Mode Max. #
Mode # Type Adapter of pages
---- ---- ------- --------
0,1 Text CGA, EGA, VGA 8
2,3 Text CGA, 4
EGA, VGA 8
7 Text MDA, Hercules 1
EGA, VGA 8
With The C Window Library, the video page displayed on the
screen is called the visible page. When creating a window,
its page number is recorded. When updating windows, the
video page number where the window resides is used to direct
the output to the appropriate video page. There are also
functions in The C Window Library that allow you to switch
video pages. With these routines, you can create very
sophisticated user interfaces. If you are using a clone
Hercules Monochrome adapter, you may have access to more
than one video page. The original Hercules card has only
one page of text memory. The problem of accessing the other
pages in the clone cards is that there is no universal way
to determine how many pages that the card has. If you are
writing an application that targets a specific Hercules
clone card, and you want to take advantage of the multiple
pages, you can modify a global variable that contains the
maximum number of available video pages, as well as the
array that contains the segment:offset of each video page.
Make sure you have the full documentation for the card, or
know off-hand the number of pages and their addresses.
Error Codes
-----------
With most of The C Window Library functions,
window_error_code, which is a global integer variable is set
to an error number when a function cannot be completed.
Throughout this documentation, you are to assume that
window_error_code is set to any error condition that is
documented for each function. The window_error_code
variable IS NOT reset when a function has been completed
successfully. A list of error codes is as follows:
Error Constant Error Code Definition
-------------- ---------- ----------
NO_HEAP_MEM -1 Not enough memory to
allocate from the
heap.
BAD_DISPLAY_PAGE -2 Video Display page is
invalid.
INVALID_VIDEO_MODE -3 Invalid video mode.
Page 6 The C Window Library Page 6
INVALID_ROWS -4 Invalid number of
screen rows specified.
BAD_WINDOW -100 Window does not exist.
BAD_WINDOW_SIZE -101 Window dimensions are
invalid.
WINDOW_NOT_OPEN -102 Window not open for
read/write.
WINDOW_BOUND -103 Coordinates specified
for window are out of
bounds.
MAX_WINDOW -104 Maximum number of
windows defined.
WINDOW_INV_PARAM -105 An invalid parameter
was encountered in the
function call.
NO_INPUT_CHARS -106 Trying to input a
field of 0 characters.
BAD_V_WINDOW -200 The virtual window
does not exist.
END_V_WINDOW -201 Internally used by The
C Window Library.
V_WINDOW_BOUND -202 Coordinates specified
for virtual window are
out of bounds.
MAX_V_WINDOW -203 Maximum number of
virtual windows
defined.
NO_ATTRIB -204 Virtual window does
not have attributes.
FILE_NO_EXIST -300 File does not exist.
FILE_CANT_CLOSE -301 Cannot close file.
FILE_CANT_OPEN -302 Cannot open file.
MENU_ENTRY_INVALID -400 An invalid menu entry
was specified.
Page 7 The C Window Library Page 7
Window Manager
--------------
The window manager is the code in The C Window Library that
handles window initialization, movement, coloring, and other
functions that control window management.
Page 8 The C Window Library Page 8
MANDATORY FUNCTIONS AND HEADER FILES
------------------------------------
The only mandatory function is WindowInitializeSystem(),
explained below. The window.h header file must be included
in any module that will call functions included in The C
Window Library.
WindowInitializeSystem()
------------------------
This function MUST be called before any other function
defined in The C Window Library. This function also sets
global variables, so it is also mandatory to call
WindowInitializeSystem() before accessing any global
variables defined by The C Window Library.
WindowInitializeSystem() detects the type of video display
used, the number of rows and columns that the screen
currently displays, and initializes data structures and
global variables.
Example:
#include "window.h"
main()
{
WindowInitializeSystem(); /* Initialization function */
/* Now it is safe to use C Window Library functions and
global variables */
}
There is no return value for WindowInitializeSystem().
Page 9 The C Window Library Page 9
CREATING WINDOWS
----------------
We will now look how a window is created by defining a
WINDOW, WPOINTER, and using the WindowSaveInitial() and
WindowInitialize() function.
The WINDOW structure and WPOINTER structure pointer
---------------------------------------------------
When a window is created, the upper left hand column and
row, the width, height, etc. must be recorded. It would be
very tedious if for every function call that acts on these
windows we have to specify width, height, upper left hand
row, etc. as function parameters. The C Window Library
conveniently has a structure called WINDOW, and its
corresponding pointer called a WPOINTER to alleviate these
problems.
When a window is created, its characteristics are stored in
a WINDOW structure, and most functions require that a pointer
to this structure be passed. This pointer is called a
WPOINTER. By only referring to the WPOINTER, argument lists
to functions become much shorter.
WindowSaveInitial()
-------------------
The WindowSaveInitial() function saves the base screen as a
window. This MUST be called prior to creating any windows.
Here is a prototype:
int WindowSaveInitial(int page)
The page argument is the video page of the base screen to
save. If you are creating windows that will be manipulated
on video page 0, you must call WindowSaveInitial() with 0 as
the argument:
#include "window.h"
main()
{
WindowInitializeSystem(); /* Initialize global variables */
WindowSaveInitial(0); /* Save video page 0's base screen */
}
Page 10 The C Window Library Page 10
In most applications, the initial screen page is page 0.
However, it is safer to use the global variable
active_video_page (explained in the IMPORTANT GLOBAL
VARIABLES section) to determine the page. If you are
changing video pages in an application, the new page has
to be initialized with WindowSaveInitial() so that the
window manager updates the screen properly when moving
windows, hiding windows, etc. This function must be called
only once in an application for each screen page desired.
If there is no error, WindowSaveInitial() returns NO_ERROR.
If there is an error, WindowSaveInitial() returns the
following values:
BAD_DISPLAY_PAGE if the page desired does not exist, or was
not detected by The C Window Library.
NO_HEAP_MEM if there is no memory to save the initial screen.
MAX_WINDOW if the maximum number of windows has already been
defined.
WindowInitialize()
------------------
The next function is WindowInitialize(). This function sets
up a window with the position on the screen to place the
window, width, height, colors, and box type. If successful,
this function returns a new WPOINTER. Here is an example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,15,NORM,NORM,SINGLEBOX);
...
}
In the above example, we have defined a variable w as having
a WPOINTER type. This variable will ultimately point to a
valid WINDOW structure. The first argument to
WindowInitialize() is a constant called BORDER. This tells
the window manager that the window desired is going to have
a border. If no border was desired, the constant would be
NOBORDER. The second and third arguments tells the window
manager the row and column of the screen where the upper
left corner of the window will be located. Since the upper
left corner of the screen is row 1, column 1, the upper left
hand corner of the window will be placed at the upper left
Page 11 The C Window Library Page 11
corner of the video screen. The fourth and fifth argument
denotes the width and the height of the window. DO NOT
INCLUDE THE BORDERS (if any) TO DETERMINE THE WIDTH AND
HEIGHT OF THE WINDOW. Our window will have a width of 30
characters and a height of 15 characters. The sixth and
seventh arguments are the video attributes of the inside of
the window and the border respectively.
The last argument tells us what type of border the window
will have. We use the constant SINGLEBOX to tell the window
manager that we want a window with a border made up of
single lines.
If there is no error, WindowInitialize() returns a valid
WPOINTER.
If there is an error, WindowInitialize() returns a
WIN_NULL_PTR (a null window pointer) and sets
window_error_code to one of the following values:
NO_HEAP_MEM if there is not enough memory to allocate for
the window structure.
BAD_WINDOW_SIZE if the dimensions for the window are too
large for the physical screen.
MAX_WINDOW if there are > 254 windows defined.
Even though there is a structure type called WINDOW, you
should always use the pointer to the structure (WPOINTER)
rather than the WINDOW structure itself.
CREATE_VIDEO_ATTRIBUTE() macro
------------------------------
Please note the use of the macro CREATE_VIDEO_ATTRIBUTE() in
the previous example to create an integer representing the
foreground and background colors. This macro uses the first
argument as the background color, and the second argument is
the foreground color. In the above example we have a
constant called NORM which uses CREATE_VIDEO_ATTRIBUTE() to
create a black background and a white foreground color
combination.
Box types
---------
For ease of use, There are predefined constants found in the
vidsys.h header file that contains definitions of common
border types. These constants are as follows:
Page 12 The C Window Library Page 12
DOUBLEBOX -- defines border characters for double box
windows.
SINGLEBOX -- defines border characters for single box
windows.
MIXEDBOX1 -- defines double lines for top and bottom and
single lines on the sides.
MIXEDBOX2 -- defines single lines for top and bottom and
double lines on the sides.
HATCHBOX1 -- defines a 'dotty' box.
HATCHBOX2 -- Another 'dotty' box.
HATCHBOX3 -- Yet another 'dotty' box.
SOLIDBOX1 -- defines a box of solid characters.
SOLIDBOX2 -- defines another box of different solid
characters.
BLANKBOX -- defines a box with a blank border. When using
these characters, do not get confused with a
blank border.
DOTTEDLINE -- defines a box with dotted lines.
Although there are predefined border types in The C Window
Library, you can define your own types. The window border
characters are represented by an 8 byte character string.
Each character in this string refers to a border character
to be used in drawing the window border. A list of what
each position in the string stands for is as follows:
position Representation
-------- ---------------------------
0 Upper left corner character.
1 Top line character.
2 Upper right corner character.
3 Left side character.
4 Right side character.
5 Bottom left corner character.
6 Bottom line character.
7 Bottom right corner character.
This character string is sent to the window functions that
call for a string of box drawing characters. For example,
you can create your own customized set of characters with
something like this:
#define MYBOXCHARS "+-+||+-+"
Page 13 The C Window Library Page 13
MYBOXCHARS is a literal string of box drawing characters.
Using the rules of box drawing characters defined above, the
upper left hand corner of the box is the plus sign, the top
line is the hyphen, the upper right and corner is the plus
sign, the left side is a pipe character, as is the right
side, and the bottom part of the box is defined the same as
the upper part. Then you would use it in a call to any
function that asks for a box drawing string like this:
w = WindowInitialize(BORDER, ... ,MYBOXCHARS);
The '... ' are the other arguments that you would normally
put for the WindowInitialize() function.
Page 14 The C Window Library Page 14
OPENING WINDOWS FOR READING AND WRITING
---------------------------------------
The next step is to allocate memory for the window's text
buffer. This will allow writing and reading characters to
the window even though it is not visible.
WindowOpen()
------------
The WindowOpen() function is used to allocate memory for the
window's text buffer. This function MUST be called if you
are going to do many of the window functions. Here is the
previous example with the WindowOpen() call:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,15,NORM,NORM,SINGLEBOX);
WindowOpen(w);
...
}
The WindowOpen() function does not display the window. The
argument tells the window manager what window to open. In
this case we want to open our new window, w. The window
buffer is cleared to spaces using the window's text
attribute, and the border (if there is a border) is drawn
internally. When a window is opened with WindowOpen(), you
can then write or read characters to a window, move, scroll,
etc. almost any function that you can do with a visible
window.
If there is no error, WindowOpen() returns NO_ERROR.
If there is an error, WindowOpen() returns one of the
following:
1) NO_HEAP_MEM if there is not enough memory to allocate for
the window buffer.
2) BAD_WINDOW if the window does not exist.
Page 15 The C Window Library Page 15
DISPLAYING WINDOWS
------------------
Now we will display the window we created in the previous
example.
The WindowDisplay() function and Explosion Effects
--------------------------------------------------
The WindowDisplay() function displays a window. Here is the
previous example with WindowDisplay() added to it:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,15,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
...
}
The first argument to WindowDisplay() is the window to
display, in our case, w is the window. The second argument
is the rank order of the window. Since the rank order we
desire is 1, this window will lie on top of all windows,
unless another window is opened with a rank of 1. Remember,
any window with a rank number n will have windows with rank
n-1, n-2,...,1 to be displayed on top of it. You can change
the rank order of a window at any time by calling
WindowDisplay() with a different rank number.
The third argument to WindowDisplay() is the explosion
effect of the window when it is displayed. There are
currently 12 ways to explode a window on the screen,
numbered from 0 thru 11. Here is an overview of each
effect:
Defined Constant Value Effect
---------------- ----- ------
NOEFFECT 0 ┌─────────────┐
│ │
│ │
│ │
│ │
│ │
│ │
│ │
└─────────────┘
Page 16 The C Window Library Page 16
EXPLODE 1 ┌─────────────────┐
│ ^ │
│ | │
│ | │
│<-- -->│
│ │
│ | │
│ | │
│ v │
└─────────────────┘
CONTRACT 2 ┌─────────────────┐
│ | │
│ | │
│ v │
│--> <--│
│ ^ │
│ | │
│ | │
└─────────────────┘
BRICKS 3 ┌────────────────┐
│█ █ █ █│
│ █ │
│ █ █ █ │
│ █ │
│ █ █ █ █ │
│█ █ │
└────────────────┘
^
MIDDLEROWOUT 4 |
┌───────────────┐
└───────────────┘
|
v
TOPBOTTOMIN 5 ┌───────────────┐
└───────────────┘
|
v
Page 17 The C Window Library Page 17
^
|
┌───────────────┐
└───────────────┘
TOPDOWN 6 ┌───────────────┐
└───────────────┘
|
v
^
BOTTOMUP 7 |
┌───────────────┐
└───────────────┘
MIDDLECOLOUT 8 ┌┐
││
││
││
<-││->
││
││
││
└┘
LEFTRIGHTIN 9 ┌┐ ┌┐
││ ││
││ ││
││ ││
││-> <-││
││ ││
││ ││
││ ││
└┘ └┘
Page 18 The C Window Library Page 18
LEFTTORIGHT 10 ┌┐
││
││
││
││->
││
││
││
││
└┘
RIGHTTOLEFT 11 ┌┐
││
││
││
<-││
││
││
││
││
└┘
If there is no error, WindowDisplay() will return NO_ERROR.
If there is an error, WindowDisplay() will return one of the
following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open with WindowOpen().
Displaying Multiple Windows
---------------------------
If you are creating multiple windows you can change the rank
of the window by calling WindowDisplay() with a different
rank number. Here is an example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue)
Page 19 The C Window Library Page 19
#define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red)
#define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green)
main()
{
int i;
WPOINTER w1,w2,w3; /* pointers to a window structures */
WindowInitializeSystem();
WindowSaveInitial(0);
w1 = WindowInitialize(BORDER,1,1,30,15,BLUEONBLACK,NORM,
SINGLEBOX);
/* define second window */
w2 = WindowInitialize(BORDER,3,3,30,15,REDONBLACK,NORM,
DOUBLEBOX);
/* define third window */
w3 = WindowInitialize(BORDER,5,5,30,15,GREENONBLACK,NORM,
SINGLEBOX);
WindowOpen(w1); /* make window 1 ok to write */
WindowOpen(w2); /* make window 2 ok to write */
WindowOpen(w3); /* make window 3 ok to write */
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
WindowDisplay(w3,3,NOEFFECT);
GET_KEY();
WindowDisplay(w2,1,NOEFFECT);
GET_KEY();
WindowDisplay(w3,1,NOEFFECT);
GET_KEY();
WindowDisplay(w1,1,NOEFFECT);
GET_KEY();
}
In the above program, w1, w2, and w3 are displayed with rank
numbers of 1, 2, and 3, respectively. The ordering means
that w1 will overlay w2, and w2 will overlay w3.
Note that after the windows w1, w2, and w3 are initially
displayed, they are redisplayed by making another call to
WindowDisplay(). You can redisplay a window and change its
rank by calling the WindowDisplay() function again. For
example, w2 is redisplayed with a rank of 1. This promotes
w2 to the top of the stack of displayed windows, and demotes
w1 with a rank of 2. Each and every window has a unique
rank number. The window manager keeps track of conflicts in
rank numbers, and adjusts the data structures involved in
maintaining the windows in working order. Therefore, there
is really no need for you to remember whether a rank number
is used or not.
The macro GET_KEY() pauses the program until you press a key.
Page 20 The C Window Library Page 20
CLOSING WINDOWS
---------------
In this section, we will discuss closing windows with and
without destroying the window pointer.
WindowClose()
-------------
The WindowClose() function hides a window from the screen
and deallocates any memory that was allocated by the
WindowOpen() function described in the previous section.
This DOES NOT destroy the window pointer (WPOINTER), however
you must call WindowOpen() again if you want to use this
window again for most other window functions. Here is the
prototype:
int WindowClose(WPOINTER w, int effect)
The first argument is the window. The second argument is
the special effect to use when closing the window. This
argument is only meaningful if the window is visible. For a
list of effects refer back to the DISPLAYING WINDOWS
section. This function can be used if you are short of
memory, but you do not want to destroy the WPOINTER.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue)
#define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red)
#define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green)
main()
{
int i;
WPOINTER w1,w2,w3;
WindowInitializeSystem();
WindowSaveInitial(0);
w1 = WindowInitialize(BORDER,1,1,30,15,BLUEONBLACK,NORM,
SINGLEBOX);
/* define second window */
w2 = WindowInitialize(BORDER,3,3,30,15,REDONBLACK,NORM,
DOUBLEBOX);
Page 21 The C Window Library Page 21
/* define third window */
w3 = WindowInitialize(BORDER,5,5,30,15,GREENONBLACK,NORM,
SINGLEBOX);
WindowOpen(w1); /* make window 1 ok to write */
WindowOpen(w2); /* make window 2 ok to write */
WindowOpen(w3); /* make window 3 ok to write */
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
WindowDisplay(w3,3,NOEFFECT);
GET_KEY();
WindowDisplay(w2,1,NOEFFECT);
GET_KEY();
WindowDisplay(w3,1,NOEFFECT);
GET_KEY();
WindowDisplay(w1,1,NOEFFECT);
GET_KEY();
WindowClose(w2,NOEFFECT);
GET_KEY();
WindowClose(w3,NOEFFECT);
GET_KEY();
WindowClose(w1,NOEFFECT);
}
The example above calls WindowClose() on all three windows.
If there are no errors, WindowClose() returns NO_ERROR.
If there are errors, WindowClose() returns the following
value:
BAD_WINDOW if the window w does not exist.
WindowFree()
------------
The WindowFree() function acts just like the WindowClose()
function except that the WPOINTER is also deallocated. This
means that the WPOINTER cannot be used anymore unless it is
initialized again using WindowInitialize(), or is assigned
to another valid WPOINTER. Here is the prototype:
int WindowFree(WPOINTER w, int effect)
Refer to WindowClose() for definitions of arguments and
return values.
Page 22 The C Window Library Page 22
WindowCloseAll()
----------------
The WindowCloseAll() function acts just like WindowClose()
function except that all windows are closed on a desired
video page. Here is the prototype:
int WindowCloseAll(int page, int effect)
The page argument is the video page of where the windows are
located. Remember that The C Window Library allows
displaying windows on video pages other than page 0 (default
page). The effect argument is the special effect to use
when closing the window. Refer to DISPLAYING WINDOWS for
the list of special effects.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue)
#define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red)
#define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green)
main()
{
int i;
WPOINTER w1,w2,w3;
WindowInitializeSystem();
WindowSaveInitial(0);
w1 = WindowInitialize(BORDER,1,1,30,15,BLUEONBLACK,NORM,
SINGLEBOX);
/* define second window */
w2 = WindowInitialize(BORDER,3,3,30,15,REDONBLACK,NORM,
DOUBLEBOX);
/* define third window */
w3 = WindowInitialize(BORDER,5,5,30,15,GREENONBLACK,NORM,
SINGLEBOX);
WindowOpen(w1); /* make window 1 ok to write */
WindowOpen(w2); /* make window 2 ok to write */
WindowOpen(w3); /* make window 3 ok to write */
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
WindowDisplay(w3,3,NOEFFECT);
WindowCloseAll(0,NOEFFECT); /* close all the windows */
}
The example above calls WindowCloseAll() to close all three
windows.
Refer to WindowClose() for return values.
Page 23 The C Window Library Page 23
WindowFreeAll()
---------------
The WindowFreeAll() function acts just like WindowClose()
function except that all windows are freed on a desired video
page. Here is the prototype:
int WindowFreeAll(int page, int effect)
The page argument is the video page of where the windows are
located. Remember that The C Window Library allows
displaying windows on video pages other than page 0 (default
page). The effect argument is the special effect to use when
closing the window. Refer to DISPLAYING WINDOWS for the list
of special effects.
Refer to WindowCloseAll() for return values.
Page 24 The C Window Library Page 24
CENTERING WINDOWS ON THE SCREEN
-------------------------------
The C Window Library allows easy centering of windows on
the screen.
WindowCenter()
--------------
The WindowCenter() function centers a window on the screen
vertically, horizontally, or both. Here is the prototype:
int WindowCenter(WPOINTER w, int option)
The first argument is the window to center, and the second
argument tells whether to center the window horizontally,
vertically, or both. The options argument must be one of
the following:
Value of
options Type of centering
------- -----------------
VERTCENTER vertical
HORIZCENTER horizontal
VERTCENTER | HORIZCENTER both horizontal and
vertical
Note the bitwise OR (|) between the constants VERTCENTER and
HORIZCENTER for both horizontal and vertical centering.
This function can be used on hidden windows and windows that
have not been opened with WindowOpen().
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
Page 25 The C Window Library Page 25
WindowCenter(w,VERTCENTER); /* center vertically */
GET_KEY();
WindowMove(w,1,1);
GET_KEY();
WindowCenter(w,HORIZCENTER); /* center horizontally */
GET_KEY();
WindowMove(w,1,1);
GET_KEY();
WindowCenter(w,VERTCENTER | HORIZCENTER); /* center both
horizontal and vertical */
GET_KEY();
WindowFree(w,NOEFFECT);
}
If there are no errors, WindowCenter() returns NO_ERROR.
If there is an error, the following value is returned:
BAD_WINDOW if the window does not exist.
Page 26 The C Window Library Page 26
CHANGING WINDOW CHARACTERISTICS
-------------------------------
In this section, we will discuss changing the window
attributes, border style, and the window's height and width.
WindowChangeTextAttribute()
---------------------------
This function changes the attribute of the text portion of
the window. The text portion is the inside of the window.
Here is a prototype:
int WindowChangeTextAttribute(WPOINTER w, int color)
where w is the WPOINTER to change the text attribute, and
color is the new color. You can use the
CREATE_VIDEO_ATTRIBUTE() macro to define the color.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowChangeTextAttribute(w,REVERSE);
}
If there is no error, WindowChangeTextAttribute() returns
NO_ERROR.
If there is an error, the following value is
returned:
BAD_WINDOW if the window does not exist.
Page 27 The C Window Library Page 27
WindowChangeBorderAttribute()
-----------------------------
This function changes the video attribute of the border of
the window. If the window does not have a border, nothing is
changed. Here is a prototype:
int WindowChangeBorderAttribute(WPOINTER w, int color)
where w is the WPOINTER to change the border attribute, and
color is the new color. You can use the
CREATE_VIDEO_ATTRIBUTE() macro to define the color.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowChangeBorderAttribute(w,REVERSE);
}
If there is no error, or if the window does not have a
border, WindowChangeBorderAttribute() returns NO_ERROR.
If there is an error, WindowChangeBorderAttribute() returns
the following value:
BAD_WINDOW if the WPOINTER w does not exist.
WindowDrawBorder()
------------------
You can also change the border type, or draw a border on an
unbordered window by calling the WindowDrawBorder()
function.
Page 28 The C Window Library Page 28
Here is a prototype:
int WindowDrawBorder(WPOINTER w, char *box)
The first argument is the window we want to change the
border of. The second argument is a string of border
characters. This string denotes the type of border that the
window should now have. In the example given below, w is
initialized with a SINGLEBOX border, but WindowDrawBorder()
changes this to a DOUBLEBOX.
The WindowDrawBorder() function is also used to draw borders
on borderless windows. When drawing borders on a NOBORDER
window, the window must not have any of its sides touching
the edges of the physical screen. In other words, the
window must "have room" for a border to be drawn. If there
is no room to draw the border, there is no change to the
window.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(NOBORDER,2,2,10,10,REVERSE,REVERSE,
SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowDrawBorder(w,DOUBLEBOX); /* Draws a double box
around NOBORDER window */
}
If there is no error, WindowDrawBorder() returns NO_ERROR.
If there is an error, WindowDrawBorder() returns one of the
following values:
BAD_WINDOW if the window w does not exist.
NO_HEAP_MEM if there is not enough memory to allocate for
temporary buffer.
Page 29 The C Window Library Page 29
WindowRemoveBorder()
--------------------
This function removes a border from a bordered window. Here
is the prototype:
int WindowRemoveBorder(WPOINTER w)
If the window does not have a border, nothing is changed.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,REVERSE,REVERSE,
SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowRemoveBorder(w); /* Removes the double box around
BORDERed window */
}
If there is no error, WindowRemoveBorder() returns NO_ERROR.
If there is an error, WindowRemoveBorder returns one of the
following values:
BAD_WINDOW if the window w does not exist.
NO_HEAP_MEM if there is not enough memory to allocate for
temporary buffer.
WindowResizeHeight()
--------------------
This function changes the inside (text portion) height of
the window. Here is a prototype:
int WindowResizeHeight(WPOINTER w, int newheight, int anchor)
The newheight argument is the new height of the window. If
the height will exceed the bounds of the screen, the window
is given its maximum height. The anchor argument determines
which side to "hold down" while the window is being resized.
If the anchor is ANCHORTOP, the top line of the window is
held in its current position and the window is resized
accordingly. If anchor is ANCHORBOTTOM, the bottom of the
Page 30 The C Window Library Page 30
window is held and the window is resized accordingly.
If there is text in the window, the text will be truncated
if the window is made shorter (unless the window is a
viewport to a virtual window. Virtual windows are discussed
in the VIRTUAL WINDOWS section).
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowResizeHeight(w,15,ANCHORTOP); /* height now is 15 */
GET_KEY();
WindowResizeHeight(w,5,ANCHORBOTTOM);/* height is now 5 */
}
If there were no errors, NO_ERROR is returned.
If there is an error, WindowResizeHeight() returns one of
the following values:
BAD_WINDOW if the WPOINTER w does not exist.
NO_HEAP_MEM if there was not enough memory to allocate
for the resized window.
WindowResizeWidth()
-------------------
This function changes the inside (text portion) width of the
window. Here is a prototype:
int WindowResizeWidth(WPOINTER w, int newwidth, int anchor)
The newwidth argument is the new width of the window. If
the width will exceed the bounds of the screen, the window
is given its maximum width. The anchor argument determines
which side to "hold down" while the window is being resized.
If the anchor is ANCHORLEFT, the left side of the window is
held in its current position and the window is resized
Page 31 The C Window Library Page 31
accordingly. If anchor is ANCHORRIGHT, the right side of
the window is held and the window is resized accordingly.
If there is text in the window, the text will be truncated
if the window is made shorter (unless the window is a
viewport to a virtual window. Virtual windows are discussed
in the VIRTUAL WINDOWS section).
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowResizeWidth(w,15,ANCHORLEFT);/* width is now 15 */
GET_KEY();
WindowResizeWidth(w,5,ANCHORRIGHT);/* width is now 5 */
}
If there were no errors, NO_ERROR is returned.
If there is an error, WindowResizeWidth() returns one of the
following:
BAD_WINDOW if the WPOINTER w does not exist.
NO_HEAP_MEM if there was not enough memory to allocate
for the resized window.
Page 32 The C Window Library Page 32
WRITING TEXT TO WINDOWS
-----------------------
There are various functions that will write text to a window.
These functions are divided into two groups: Functions that
specify a null terminated string, and functions that require
the length of the string of characters to write to be an
explicit argument.
Null Terminated Write Functions
-------------------------------
WindowWriteString()
-------------------
The WindowWriteString() function writes a null terminated
string of characters to a window at a specified row and
column of the window. If the string is too long to fit in
the boundaries of the window, the string is clipped
(truncated) to fit in the boundaries of the window.
Here is the prototype:
int WindowWriteString(WPOINTER w, char *string, int row,
int col)
The first argument is the window to write the string to. The
second argument is the null terminated string to write. The
third and fourth arguments are the row and column of the
window to place the string. The video attribute used when
writing the string is the video attribute of the inside of
the window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World",i,1);
}
Page 33 The C Window Library Page 33
The above example writes the string "Hello World" to each
line of the window w.
If there is no error WindowWriteString() returns NO_ERROR.
If there is an error WindowWriteString() returns the
following:
BAD_WINDOW if the WPOINTER w does not exist.
WINDOW_BOUND if the row or column specified are out of bounds
of the window.
WINDOW_NOT_OPEN if the window was not open for writing (did
not use WindowOpen() on the window)
WindowWriteStringAttr()
-----------------------
The WindowWriteStringAttr() function works the same as the
WindowWriteString() function except that an extra argument
determines the color used to write the string. Here is the
prototype:
int WindowWriteStringAttr(WPOINTER w, char *string, int row,
int col, int attr)
The first argument is the window to write the string to. The
second argument is the null terminated string to write. The
third and fourth arguments are the row and column of the
window to place the string. The last argument is the video
attribute to use.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
for (i=1;i<=10;i++)
WindowWriteStringAttr(w,"Hello World",i,1,REVERSE);
}
Page 34 The C Window Library Page 34
The above example writes the string "Hello World" to each
line of the window w using the video attribute defined by the
constant REVERSE.
The return values to WindowWriteStringAttr() are the same as
WindowWriteString().
WindowWriteCenterString()
-------------------------
The WindowWriteCenterString() function centers a null
terminated string in a window. Here is a prototype:
int WindowWriteCenterString(WPOINTER w, char *string,
int row)
The first argument is the window. The second argument is the
string to write. The third argument is the row that the
string will be centered.
The attribute used to write the string is the attribute of
the inside of the window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
for (i=1;i<=10;i++)
WindowWriteCenterString(w,"Hello World",i);
}
The above example writes and centers the string "Hello World"
to each line of the window w.
The return values for WindowWriteCenterString() are the same
as WindowWriteString().
Page 35 The C Window Library Page 35
WindowWriteCenterStringAttr()
-----------------------------
The WindowWriteCenterStringAttr() function works the same as
the WindowWriteCenterString() function except that an extra
argument determines the color used to write the string. Here
is the prototype:
int WindowWriteCenterStringAttr(WPOINTER w, char *string,
int row, int attr)
The first argument is the window. The second argument is the
string to write. The third argument is the row that the
string will be centered. The last argument is the video
attribute to use to write the string.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
for (i=1;i<=10;i++)
WindowWriteCenterStringAttr(w,"Hello World",i,REVERSE);
}
The above example writes and centers the string "Hello World"
to each line of the window w using REVERSE as the video
attribute.
The return values for WindowWriteCenterStringAttr() are the
same as WindowWriteString().
WindowWriteStringCC()
---------------------
Centers and writes a string around a column of the window
(the CC stands for Centered Column). If the string is longer
than the width of the window, the string is placed on column
1 of the window and is clipped at the right edge of the
window. Here is the prototype:
Page 36 The C Window Library Page 36
The attribute used to write the string is the attribute of
the inside of the window.
int WindowWriteStringCC(WPOINTER w, char *string, int row)
The first argument is the window. The second argument is the
string. The third argument is the row to write the string,
and the last argument is the column to center the string on.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteStringCC(w,"This",1,10);
WindowWriteStringCC(w,"is",2,10);
WindowWriteStringCC(w,"centered",3,10);
WindowWriteStringCC(w,"around",4,10);
WindowWriteStringCC(w,"column",5,10);
WindowWriteStringCC(w,"10",6,10);
}
The example above writes the text centered around column 10
of the window w.
The return values for WindowWriteStringCC() are the same as
WindowWriteString().
WindowWriteStringCCAttr()
-------------------------
The WindowWriteStringCCAttr() function works the same as the
WindowWriteStringCC() function except that an extra argument
determines the color used to write the string. Here is the
prototype:
int WindowWriteStringCCAttr(WPOINTER w, char *string,
int row, int col, int attr)
The first argument is the window. The second argument is the
Page 37 The C Window Library Page 37
string to write. The third argument is the row that the
string will be centered. The column argument is the column
to center the string on. The last argument is the video
attribute to use to write the string.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteStringCCAttr(w,"This",1,10,REVERSE);
WindowWriteStringCCAttr(w,"is",2,10,REVERSE);
WindowWriteStringCCAttr(w,"centered",3,10,REVERSE);
WindowWriteStringCCAttr(w,"around",4,10,REVERSE);
WindowWriteStringCCAttr(w,"column",5,10,REVERSE);
WindowWriteStringCCAttr(w,"10",6,10,REVERSE);
}
The example above writes the text centered around column 10
of the window w using the video attribute REVERSE.
The return values for WindowWriteStringCCAttr() are the same
as WindowWriteString().
WindowWriteStringRJ()
---------------------
The WindowWriteStringRJ() function writes a right justified
string. Here is the prototype:
int WindowWriteStringRJ(WPOINTER w, char *string, int row,
int col)
The first argument is the window. The second argument is the
string. The third argument is the row to write the string,
and the last argument is the column to place the right edge
of the string.
Page 38 The C Window Library Page 38
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteStringRJ(w,"This",1,10);
WindowWriteStringRJ(w,"is",2,10);
WindowWriteStringRJ(w,"right",3,10);
WindowWriteStringRJ(w,"justified",4,10);
WindowWriteStringRJ(w,"on ",5,10);
WindowWriteStringRJ(w,"column",6,10);
WindowWriteStringRJ(w,"10",7,10);
}
The example above writes the text right justified on column
10 of the window w.
The attribute used to write the string is the attribute of
the inside of the window.
The return values for WindowWriteStringRJ() are the same as
WindowWriteString().
WindowWriteStringRJAttr()
-------------------------
The WindowWriteStringRJAttr() function works the same as the
WindowWriteStringRJ() function except that an extra argument
determines the color used to write the string. Here is the
prototype:
int WindowWriteStringRJAttr(WPOINTER w, char *string,
int row, int col, int attr)
The first argument is the window. The second argument is the
string to write. The third argument is the row to write the
string. The col is the column to right justify the string.
The last argument is the video attribute to use to write the
string.
Page 39 The C Window Library Page 39
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteStringRJAttr(w,"This",1,10,REVERSE);
WindowWriteStringRJAttr(w,"is",2,10,REVERSE);
WindowWriteStringRJAttr(w,"right",3,10,REVERSE);
WindowWriteStringRJAttr(w,"justified",4,10,REVERSE);
WindowWriteStringRJAttr(w,"on ",5,10,REVERSE);
WindowWriteStringRJAttr(w,"column",6,10,REVERSE);
WindowWriteStringRJAttr(w,"10",7,10,REVERSE);
}
The example above writes the text right justified at column
10 of the window w using the video attribute REVERSE.
The return values for WindowWriteStringRJAttr() are the same
as WindowWriteString().
Length Controlled Write Functions
---------------------------------
The upcoming functions must have the length explicitly stated
as one of the arguments. These functions do not stop writing
characters if the null character in the string to write is
reached.
WindowWriteCharacters()
-----------------------
This function writes characters from a buffer to the window.
Here is the prototype:
int WindowWriteCharacters(WPOINTER w, char *buffer, int row,
int col, int length)
The first argument is the window. The second argument is a
Page 40 The C Window Library Page 40
pointer to the buffer where the characters are stored. The
third and fourth arguments are the (row,col) position in the
window to write the string, and the last argument is the
number of characters from buffer to write. The attribute
used is the attribute of the inside of the window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buf[] = "Hello World!!";
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteCharacters(w,buf,1,1,11);
WindowWriteCharacters(w,buf,2,1,13);
}
The return values for WindowWriteCharacters() are the same as
WindowWriteString().
WindowWriteAttributes()
-----------------------
This function writes attributes from a buffer to the window.
Here is the prototype:
int WindowWriteAttributes(WPOINTER w, char *buffer, int row,
int col, int length)
The first argument is the window. The second argument is a
pointer to the buffer where the attributes are stored. The
third and fourth arguments are the (row,col) position in the
window to write the string, and the last argument is the
number of attributes from buffer to write.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
Page 41 The C Window Library Page 41
WPOINTER w;
char buf[13];
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<13;i++)
if (i % 2)
buf[i] = NORM;
else
buf[i] = REVERSE;
WindowWriteString(w,"Hello World!!",1,1);
GET_KEY();
WindowWriteAttributes(w,buf,1,1,13); /* Writes alternating
NORM and REVERSE
attributes */
}
The return values for WindowWriteAttributes() are the same as
WindowWriteString().
WindowWriteCharAndAttr()
------------------------
The WindowWriteCharAndAttr() function writes a string of
character/attribute pairs to a window. Use this function if
you have created a string of character/attribute pairs, and
want to output them easily. The string consists of character
and attributes in the following manner:
char-attr-char-attr...
Each character is followed by its corresponding video
attribute.
Here is the prototype:
int WindowWriteCharAndAttr(WPOINTER w, char *buffer, int row,
int col, int length)
The first argument is the window. The second is the buffer
where the character and attributes are stored. The third and
Page 42 The C Window Library Page 42
fourth is the (row,col) position in the window to write, and
the length argument is the number of character/attribute
pairs from the buffer to write. Please note the difference
in the meaning of the length argument in this function as
opposed to its use in the preceding functions.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buf[26];
char *str = "Hello World!!";
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<26;i+=2,str++)
{
buf[i] = *str;
buf[i+1] = NORM;
}
WindowWriteCharAndAttr(w,buf,1,1,13);
}
The return values for WindowWriteCharAndAttr() are the same as
WindowWriteString().
WindowWriteCharactersAttr()
---------------------------
The WindowWriteCharactersAttr() function writes characters
from a buffer to a window. The difference between this
function and WindowWriteCharacters() is that a video
attribute is specified. Here is the prototype:
int WindowWriteCharactersAttr(WPOINTER w, char *buffer,
int row, int col, int attr,
int length)
The attr argument is the video attribute to use when writing
the characters.
Page 43 The C Window Library Page 43
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
char buf[] = "Hello World!!";
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteCharactersAttr(w,buf,2,1,REVERSE,13);
}
The return values for WindowWriteCharactersAttr() are the
same as WindowWriteString().
WindowWriteRepeatAttribute()
----------------------------
The WindowWriteRepeatAttribute() function writes an attribute
a specified number of times to a window. Here is a
prototype:
int WindowWriteRepeatAttribute(WPOINTER w, int attr, int row,
int col, int count)
The attr argument is the attribute to use. The count
argument specifies the number of times to write the attribute
attr to the window starting at (row,col).
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
Page 44 The C Window Library Page 44
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Hello World!!",1,1);
GET_KEY();
WindowWriteRepeatAttribute(w,REVERSE,1,1,13);
}
The example above illustrates that the
WindowWriteRepeatAttribute() writes the REVERSE attribute 13
times starting at row 1, column 1 of the window w.
The return values for WindowWriteRepeatAttribute() are the
same as WindowWriteString().
WindowWriteRepeatCharacter()
----------------------------
The WindowWriteRepeatCharacter() function writes a character
a specified number of times to a window. Here is a
prototype:
int WindowWriteRepeatCharacter(WPOINTER w, int ch, int row,
int col, int count)
The count argument is the character to use. The count
argument specifies the number of times to write the character
ch to the window starting at (row,col).
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteRepeatCharacter(w,'a',1,1,5);
WindowWriteRepeatCharacter(w,'b',2,1,5);
WindowWriteRepeatCharacter(w,'c',3,1,5);
}
The example above illustrates that the
WindowWriteRepeatCharacter() writes the letter 'a', 'b', and
Page 45 The C Window Library Page 45
'c' 5 times on rows 1, 2, and 3 respectively.
The return values for WindowWriteRepeatCharacter() are the
same as WindowWriteString().
Formatted Write Functions
-------------------------
These functions write formatted output to windows just like
the printf() function. There are two functions that do this,
namely WindowPrintf() and WindowPrintfAttr(). These
functions use a format string that is similar to the format
string found in printf(). For example, %d, %s, %lf, etc. and
most of the escape sequences are supported. The list of
escape sequences supported are as follows:
\n - newline
\b - backspace
\t - tab
\a - bell
\r - carriage return
\x - hexadecimal
Where output is placed in the window
------------------------------------
The row and column of where the string will be written is
determined by the window's logical cursor. The logical
cursor is advanced by both of these functions to one column
position after the last character is printed. If you want to
start at a particular row and column of the window, you must
move the cursor yourself by calling the WindowMoveCursor()
function. This function is explained later in the CURSOR
POSITIONING IN WINDOWS section. If the window is displayed,
the logical cursor of the window is equivalent to the screen
cursor. If the output to the window will be obscured by
other windows, the screen cursor will also be hidden.
When the window is first opened using WindowOpen(), the
logical cursor is automatically moved to (1,1) of the window.
WindowSetWrap()
---------------
With these functions, any text that will exceed the
boundaries of the window will be wrapped to the next line.
If the output will exceed the last row of the window, the
window is automatically scrolled up by one line. This is the
default action that is taken when characters exceed the right
edge of the window. If you want the output clipped instead
of wrapped, you must set the window's wrap flag using the
Page 46 The C Window Library Page 46
WindowSetWrap() function.
The WindowSetWrap() function sets the window's wrap flag to
either on or off. Here is the prototype:
int WindowSetWrap(WPOINTER w, int option)
The second argument will be 0 if you want to turn the wrap
flag off, or 1 if you want to turn it on. If the wrap flag
is off, the output generated by WindowPrintf() and
WindowPrintfAttr() will be terminated when the right edge
of the window is reached. If the wrap flag is on, the output
is wrapped to the next line when the right edge is reached,
and the window will be scrolled up by one line if the output
will exceed the last row.
You can set the wrap flag to a window at any time.
WindowPrintf()
--------------
The WindowPrintf() function writes formatted output to the
window. Here is the prototype:
int WindowPrintf(WPOINTER w, char *format [,arg1,...])
The first argument is the window. The second argument is a
format string. The rest of the arguments are optional
arguments that are written to the window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char *s1 = "This string will wrap around to the next line\n";
char *s2 = "This escape code will ring the bell \a";
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowPrintf(w,"3+2 is equal to %d\n",3+2);
GET_KEY();
WindowPrintf(w,"i is equal to %d\nj is equal to %lf\n",i,j);
GET_KEY();
WindowPrintf(w,s1);
GET_KEY();
Page 47 The C Window Library Page 47
WindowPrintf(w,s2);
}
The above example illustrates how WindowPrintf() is used to
print formatted strings.
The return values for WindowPrintf() are the same as
WindowWriteString().
WindowPrintfAttr()
------------------
The WindowPrintfAttr() function writes formatted output to
the window. The difference between WindowPrintf() and
WindowPrintfAttr() is that WindowPrintfAttr() uses a video
attribute specified as an argument. Here is the prototype:
int WindowPrintfAttr(WPOINTER w, int attr,
char *format [,arg1,...])
The first argument is the window. The second argument is the
video attribute to use. The third argument is the format
string. The rest of the arguments are optional arguments
that are written to the window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
char *s1 = "This string will wrap around to the next line\n";
char *s2 = "This escape code will ring the bell \a";
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowPrintfAttr(w,REVERSE,"3+2 is equal to %d\n",3+2);
GET_KEY();
WindowPrintfAttr(w,REVERSE,
"i is equal to %d\nj is equal to %lf\n",i,j);
GET_KEY();
WindowPrintfAttr(w,REVERSE,s1);
GET_KEY();
WindowPrintfAttr(w,REVERSE,s2);
}
Page 48 The C Window Library Page 48
The above example illustrates how WindowPrintfAttr() is used
to print formatted strings.
The return values for WindowPrintfAttr() are the same as
WindowWriteString().
Page 49 The C Window Library Page 49
WRITING TITLES TO WINDOWS
-------------------------
This section only applies to bordered windows. There are two
methods of writing text to the top or bottom border of a
window. Each method has its advantages and disadvantages.
The first method is to explicitly write to the border of the
window. Except for the WindowPrintf...() functions, if you
specify the row number to be 0, the text is written on the
upper border of the window. If the row number is equal to the
window height + 1, the text is written on the lower border of
the window. To access the window's height use the macro
WINDOW_HEIGHT() described later in the WINDOW MACROS section.
If you want to write a formatted string on the border of the
window, use the standard library function sprintf() to create
a string of formatted output, and then write this string with
one of the WindowWrite...() functions.
Any text that is written on the borders of a window are not
retained if the window is resized using one of the
WindowResize...() functions, or if the border is changed
using WindowDrawBorder(). Therefore it is a good idea to
maintain what is on the borders of the window in your own
string variables.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
/* Specify row 0 to write on */
WindowWriteCenterString(w,"This is a title",0);
WindowWriteCenterString(w,"This is a title",
WINDOW_HEIGHT(w) + 1);
}
Page 50 The C Window Library Page 50
The second method is writing a string of text to either the
top or bottom border by using the WindowTitle...() functions.
The advantage of using these functions is that the strings
are retained automatically if the window is resized or the
border type is changed. Another advantage is that if the
title does not fit in the boundaries of the window, the title
is truncated, but the full title is retained in a buffer. If
the window is later resized so that the title can fit, the
full title will appear on the border.
The disadvantage is that only one string of text is allowed
for the top and bottom borders, and there are only three
positions on each border to place the title.
WindowTitleTop()
----------------
The WindowTitleTop() function writes a title to the top
border of a window. Here is the prototype:
int WindowTitleTop(WPOINTER w, char *title, int pos)
The first argument is the window to write the title. The
second argument is the title to write. The third argument is
the position to place the title. Here is a list of valid
constants to use for the position:
TITLELEFT - Places the title starting at column 1 of the
window.
TITLECENTER - Centers the title in the window.
TITLERIGHT - Right justifies the title to the last column
of the window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
/* left justify title */
Page 51 The C Window Library Page 51
WindowTitleTop(w,"This is a title",TITLELEFT);
GET_KEY();
/* center title */
WindowTitleTop(w,"This is a title",TITLECENTER);
GET_KEY();
/* right justify title */
WindowTitleTop(w,"This is a title",TITLERIGHT);
}
If there are no errors, WindowTitleTop() returns NO_ERROR.
If there are errors, WindowTitleTop() returns one of the
following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for writing (use
WindowOpen())
WindowTitleBottom()
-------------------
The WindowTitleBottom() function writes a title to the bottom
border of a window. Here is the prototype:
int WindowTitleBottom(WPOINTER w, char *title, int pos)
The first argument is the window to write the title. The
second argument is the title to write. The third argument is
a constant that denotes the position to place the title. A
list of valid constants can be found in the description of
WindowTitleBottom() described above.
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
/* left justify title */
WindowTitleBottom(w,"This is a title",TITLELEFT);
GET_KEY();
Page 52 The C Window Library Page 52
/* center title */
WindowTitleBottom(w,"This is a title",TITLECENTER);
GET_KEY();
/* right justify title */
WindowTitleBottom(w,"This is a title",TITLERIGHT);
}
If there are no errors, WindowTitleBottom() returns NO_ERROR.
If there are errors, WindowTitleBottom() returns one of the
following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for writing (use
WindowOpen())
WindowTitleTopAttr()
--------------------
The WindowTitleTopAttr() function writes a title to the top
border of a window with a specified color attribute. Here is
the prototype:
int WindowTitleTopAttr(WPOINTER w, char *title, int pos,
int attr)
The first argument is the window to write the title. The
second argument is the title to write. The third argument is
a constant that denotes the position to place the title. A
list of valid constants can be found in the description of
WindowTitleTopAttr() described above. The fourth argument is
the color attribute to use.
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
Page 53 The C Window Library Page 53
/* left justify title */
WindowTitleTopAttr(w,"This is a title",TITLELEFT,REVERSE);
GET_KEY();
/* center title */
WindowTitleTopAttr(w,"This is a title",TITLECENTER,REVERSE);
GET_KEY();
/* right justify title */
WindowTitleTopAttr(w,"This is a title",TITLERIGHT,REVERSE);
}
If there are no errors, WindowTitleTopAttr() returns NO_ERROR.
If there are errors, WindowTitleTopAttr() returns one of the
following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for writing (use
WindowOpen())
WindowTitleBottomAttr()
-----------------------
The WindowTitleBottomAttr() function writes a title to the
bottom border of a window with a specified color attribute.
Here is the prototype:
int WindowTitleBottomAttr(WPOINTER w, char *title, int pos,
int attr)
The first argument is the window to write the title. The
second argument is the title to write. The third argument is
a constant that denotes the position to place the title. A
list of valid constants can be found in the description of
WindowTitleBottomAttr() described above. The fourth argument
is the color attribute to use.
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
Page 54 The C Window Library Page 54
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
/* left justify title */
WindowTitleBottomAttr(w,"This is a title",TITLELEFT,
REVERSE);
GET_KEY();
/* center title */
WindowTitleBottomAttr(w,"This is a title",TITLECENTER,
REVERSE);
GET_KEY();
/* right justify title */
WindowTitleBottomAttr(w,"This is a title",TITLERIGHT,
REVERSE);
}
If there are no errors, WindowTitleBottomAttr() returns
NO_ERROR.
If there are errors, WindowTitleBottomAttr() returns one of
the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for writing (use
WindowOpen())
Page 55 The C Window Library Page 55
READING CHARACTERS AND ATTRIBUTES FROM WINDOWS
----------------------------------------------
With The C Window Library, you can read the contents of a
window into a character buffer. These functions provide the
programmer with the contents of the window at any time. The
functions to perform this are WindowReadAttributes(),
WindowReadCharacters(), and WindowReadCharAndAttr().
WindowReadCharacters()
----------------------
The WindowReadCharacters() function reads the characters from
a window into a buffer. Here is the prototype.
int WindowReadCharacters(WPOINTER w, char *buffer, int row,
int col, int length)
The first argument is the window. The second argument is the
buffer to store the characters in. The third and fourth
arguments are the (row,col) position in the window to start
reading from. The last argument is the number of characters
to read.
You must make sure that buffer has enough room to hold all of
the characters read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buf[14] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Hello World!!",1,1);/* Write String */
WindowReadCharacters(w,buf,1,1,13); /* Read characters */
GET_KEY();
WindowWriteString(w,buf,2,1); /* Write what we have read */
}
The example above illustrates the use of
WindowReadCharacters(), which reads the window's contents
Page 56 The C Window Library Page 56
starting at (1,1) of the window. This happens to be the
string "Hello World!!". After GET_KEY() is called, the
results of the buffer are written on line 2 of the window.
If the length exceeds the right edge of the window,
WindowReadCharacters() will read up to the right edge of the
window.
If there are no errors, WindowReadCharacters() returns
NO_ERROR. If there are errors, WindowReadCharacters()
returns one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for reading (use
WindowOpen())
WINDOW_BOUND if the row or column specified in the window is
out of bounds.
WindowReadAttributes()
----------------------
The WindowReadAttributes() function reads the attributes from
a window into a buffer. Here is the prototype.
int WindowReadAttributes(WPOINTER w, char *buffer, int row,
int col, int length)
The first argument is the window. The second argument is the
buffer to store the attributes in. The third and fourth
arguments are the (row,col) position in the window to start
reading from. The last argument is the number of attributes
to read.
You must make sure that buffer has enough room to hold all of
the attributes read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buf[14] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
Page 57 The C Window Library Page 57
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Hello World!!",1,1);/* Write String */
WindowReadAttributes(w,buf,1,1,13); /* Read attributes */
GET_KEY();
WindowWriteString(w,buf,2,1); /* Write what we have read */
}
The example above illustrates the use of
WindowReadAttributes(), which reads the window's attribute
contents starting at (1,1) of the window. This happens to be
the attributes of the string "Hello World!!", which is the
NORM attribute. After GET_KEY() is called, the results of
the buffer are written on line 2 of the window.
If the length exceeds the right edge of the window,
WindowReadAttributes() will read up to the right edge of the
window.
If there are no errors, WindowReadAttributes() returns
NO_ERROR.
If there are errors, WindowReadAttributes() returns one of
the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for reading (use
WindowOpen())
WINDOW_BOUND if the row or column specified in the window is
out of bounds.
WindowReadCharAndAttr()
----------------------
The WindowReadCharAndAttr() function reads
character/attribute pairs from a window into a buffer. Here
is the prototype.
int WindowReadCharAndAttr(WPOINTER w, char *buffer, int row,
int col, int length)
The first argument is the window. The second argument is the
buffer to store the character/attribute pairs in. The third
and fourth arguments are the (row,col) position in the window
to start reading from. The last argument is the number of
character/attribute pairs to read.
Page 58 The C Window Library Page 58
You must make sure that buffer has enough room to hold all of
the character/attribute pairs read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buf[27] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Hello World!!",1,1);/* Write String */
WindowReadCharAndAttr(w,buf,1,1,13);
GET_KEY();
WindowWriteCharAndAttr(w,buf,2,1,13); /* Write what we have
read */
}
The example above illustrates the use of
WindowReadCharAndAttr(), which reads the window's
character/attribute contents starting at (1,1) of the window.
This happens to be the characters/attributes of the string
"Hello World!!". After GET_KEY() is called, the results of
the buffer are written on line 2 of the window.
If the length exceeds the right edge of the window,
WindowReadCharAndAttr() will read up to the right edge of the
window.
If there are no errors, WindowReadCharAndAttr() returns
NO_ERROR.
If there are errors, WindowReadCharAndAttr() returns one of
the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for reading (use
WindowOpen())
WINDOW_BOUND if the row or column specified in the window is
out of bounds.
Page 59 The C Window Library Page 59
HIDING WINDOWS
--------------
With The C Window Library, you can hide windows at any time
without disturbing the contents of other windows.
WindowHide()
------------
The WindowHide() function hides a window on the screen from
view. The window retains all text and shadows that may be
present. Here is a prototype:
int WindowHide(WPOINTER w, int effect)
The first argument is the window, and the last argument is
the special effect to use when hiding the window. For a list
of special effects, refer to the DISPLAYING WINDOWS section.
Example :
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white)
#define BLACKONWHITE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w1,w2,w3;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
/* Initialize all windows */
w1 = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
w2 = WindowInitialize(BORDER,2,2,20,10,REDONWHITE,NORM,
DOUBLEBOX);
w3 = WindowInitialize(BORDER,3,3,20,10,BLACKONWHITE,NORM,
SINGLEBOX);
/* Open all windows */
WindowOpen(w1);
WindowOpen(w2);
WindowOpen(w3);
/* Display All windows */
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
WindowDisplay(w3,3,NOEFFECT);
WindowWriteString(w1,"This is window 1",1,1);
Page 60 The C Window Library Page 60
WindowWriteString(w2,"This is window 2",2,1);
WindowWriteString(w3,"This is window 3",3,1);
GET_KEY();
WindowHide(w3,NOEFFECT);
GET_KEY();
WindowHide(w2,BRICKS);
GET_KEY();
WindowHide(w1,CONTRACT);
}
The example initializes, opens, and displays three windows.
Note that you can hide windows regardless of the order in
which they were displayed. This makes for very flexible
window management.
If there is no error, WindowHide() returns NO_ERROR.
The only error that can occur is if the WPOINTER w does not
exist. WindowHide() returns BAD_WINDOW if this is the case.
Page 61 The C Window Library Page 61
CREATING COPIES OF A WINDOW
---------------------------
You can create copies of a window without going through the
WindowInitialize(), WindowOpen(), etc. cycle.
WindowCopy()
------------
The WindowCopy() function makes a copy of a previous window.
The copy will have the same colors, border type, shadow, and
may have the same text as a previous window. If the original
window is a viewport on a virtual window (virtual windows are
discussed later in the VIRTUAL WINDOWS section), the copy can
also be made a viewport on the same virtual window. The only
thing that will not be copied is the (row,col) of the
original window. You supply the position of the new window.
Here is the prototype:
WPOINTER WindowCopy(WPOINTER w, int row, int col, int options)
Please note that WindowCopy() returns a new WPOINTER. You
must assign the return value to a WPOINTER or you will not
get easy access to the newly created window.
The first argument is the original window to copy. This
window must already exist. The second and third arguments
are the coordinates of where to place the new window. The
last argument are additional options that control whether the
window will contain the same text as the previous window, and
if the new window will be made a viewport if the original
window is a viewport. The constants used for options is as
follows:
options action
------- ------
COPYTEXT Makes a copy of the text area of the
original window.
MAKEVIEWPORT Turns the copy into a viewport if the
original is a viewport.
NO_OPTIONS No options desired.
As was stated before, viewports are discussed in the VIRTUAL
WINDOW section of the manual. If options is NO_OPTIONS, the
windows size, border type, shadow (if there is a shadow) and
colors are copied.
Page 62 The C Window Library Page 62
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w,w2;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,45,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,
"This will be copied to the new window",1,1);
GET_KEY();
w2 = WindowCopy(w,3,3,COPYTEXT); /* Make a copy of w */
WindowDisplay(w2,1,NOEFFECT); /* Display this copy */
GETKEY();
WindowFreeAll(0,NOEFFECT);
}
If there is no error, WindowCopy() returns a valid WPOINTER.
If there is an error, WindowCopy() returns a WIN_NULL_PTR (a
null window pointer) and sets window_error_code to one of the
following values:
NO_HEAP_MEM if there is not enough memory to allocate for
the window structure.
BAD_WINDOW_SIZE if the dimensions for the window are too
large for the physical screen.
MAX_WINDOW if there are > 254 windows defined.
Page 63 The C Window Library Page 63
SCROLLING TEXT IN WINDOWS
-------------------------
With The C Window Library, you can scroll text in a window
up, or down, or scroll just particular regions of a window.
The functions used to scroll windows are WindowScroll(),
WindowScrollAttr(), WindowScrollRegion(), and
WindowScrollRegionAttr().
When specifying a direction, use the constant UP to scroll up
or DOWN to scroll down. These constants are defined in
window.h.
WindowScroll()
--------------
If you want to scroll the entire window either up or down,
you can use the WindowScroll() function. Here is a
prototype:
int WindowScroll(WPOINTER w, int numlines, int direction)
The first argument is the window to scroll. The second
argument is the number of lines to scroll. The last argument
is the direction to scroll the window (either UP or DOWN).
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<10;i++)
WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20);
GET_KEY();
WindowScroll(w,1,UP);
GET_KEY();
WindowScroll(w,3,DOWN);
}
The above example creates text using
WindowWriteRepeatCharacter() function. The WindowScroll()
Page 64 The C Window Library Page 64
calls will scroll the window up by one line, and then scroll
the window down by 3 lines.
If there is no error, WindowScroll() returns NO_ERROR.
If there is an error, WindowScroll() will return the
following values:
BAD_WINDOW if the WPOINTER w does not exist.
WINDOW_NOT_OPEN if the window was not open for writing (use
WindowOpen() to open the window for writing).
WindowScrollRegion()
--------------------
The WindowScrollRegion() functions scrolls a specified region
of a window. To use the WindowScrollRegion() function, you
must describe the rectangular region to scroll. Here is the
prototype:
int WindowScrollRegion(WPOINTER w, int numlines, int urow,
int ucol, int lrow,
int lcol, int direction)
Arguments 3 thru 6 describe the rectangular region. They are
in the order of upper left row, upper left column, lower
right row, lower right column. All of these coordinates are
window relative. The second argument is the number of lines
to scroll. The last argument is the direction.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<10;i++)
WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20);
GET_KEY();
WindowScrollRegion(w,1,2,2,4,10,UP);
GET_KEY();
WindowScrollRegion(w,3,7,2,9,8,DOWN);
}
Page 65 The C Window Library Page 65
The above example creates text using
WindowWriteRepeatCharacter() function. The first
WindowScrollRegion() call will scroll the region described by
the rectangular coordinates (2,2) and (4,10). This region is
scrolled up one line. The second call to
WindowScrollRegion() scrolls the region defined by the
rectangular region (7,2) and (9,8). This region is scrolled
down by three lines.
If there is no error, WindowScrollRegion() returns NO_ERROR.
If there is an error, the WindowScrollRegion() function will
return of the following values:
BAD_WINDOW if the WPOINTER w does not exist.
WINDOW_BOUND if the rectangular region defined is out of
bounds of the window.
WINDOW_NOT_OPEN if the window was not open for writing (use
WindowOpen() to open the window for writing).
WindowScrollAttr()
------------------
This function works the same way as the WindowScroll()
function except that an attribute is defined for the blank
lines that are created when the window is scrolled. Here is
a prototype:
int WindowScrollAttr(WPOINTER w, int numlines, int direction,
int attr)
The last argument is the attribute to use for the blank lines
created.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
Page 66 The C Window Library Page 66
for (i=0;i<10;i++)
WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20);
GET_KEY();
WindowScrollAttr(w,1,UP,REDONWHITE);
GET_KEY();
WindowScrollAttr(w,3,DOWN,REDONWHITE);
}
The above example creates text using
WindowWriteRepeatCharacter() function. The
WindowScrollAttr() calls will scroll the window up by one
line, and then scroll the window down by 3 lines with both
scrolls using REDONWHITE as the video attribute.
WindowScrollAttr() returns the same values as WindowScroll().
WindowScrollRegionAttr()
------------------------
This function works the same way as the WindowScrollRegion()
function except that an attribute is defined for the blank
lines that are created when the window is scrolled. Here is
a prototype:
int WindowScrollRegionAttr(WPOINTER w, int numlines, int
int urow, int ucol, int lrow,
int lcol, int direction, int attr)
The last argument is the attribute to use for the blank lines
created.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<10;i++)
WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20);
GET_KEY();
WindowScrollRegionAttr(w,1,3,5,6,15,UP,REDONWHITE);
Page 67 The C Window Library Page 67
GET_KEY();
WindowScrollRegionAttr(w,3,8,4,10,12,DOWN,REDONWHITE);
}
The above example creates text using
WindowWriteRepeatCharacter() function. The first
WindowScrollRegionAttr() call will scroll the region
described by the rectangular coordinates (2,2) and (4,10).
This region is scrolled one line. The second call to
WindowScrollRegionAttr() scrolls the region defined by the
rectangular region (7,2) and (9,8). This region is scrolled
down by three lines. All blank lines use the video attribute
REDONWHITE.
WindowScrollRegionAttr() returns the same values as
WindowScrollRegion().
Page 68 The C Window Library Page 68
CLEARING WINDOWS
----------------
The C Window Library contains functions that clears the
entire window, or clears defined rectangular regions of the
window.
WindowClear()
-------------
The WindowClear() function clears an entire window to spaces.
The attribute used is the current attribute of the text area
of the window. Here is the prototype:
int WindowClear(WPOINTER w)
The only argument is the window to clear.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World!!",i,1);
GET_KEY();
WindowClear(w);
}
If there is no error, WindowClear() returns NO_ERROR.
If there is an error, WindowClear() returns the following
values:
BAD_WINDOW if the WPOINTER w does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use
WindowOpen() to open the window for writing).
Page 69 The C Window Library Page 69
WindowClearAttr()
-----------------
The WindowClearAttr() function works the same way as the
WindowClear() function except that an attribute is specified.
Here is the prototype:
int WindowClearAttr(WPOINTER w, int attr)
The second argument is the video attribute to use.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World!!",i,1);
GET_KEY();
WindowClearAttr(w,REDONWHITE);
}
The return values for WindowClearAttr() are the same as
WindowClear().
WindowClearRegion()
-------------------
The WindowClearRegion() function clears a region of a window.
To use the WindowClearRegion() function, you must describe
the rectangular region to clear. Here is the prototype:
int WindowClearRegion(WPOINTER w, int urow, int ucol,
int lrow, int lcol)
where (urow,ucol) describes the upper left of the rectangle
and (lrow,lcol) is the lower right of the window. These
coordinates are window relative.
Page 70 The C Window Library Page 70
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World!!",i,1);
GET_KEY();
WindowClearRegion(w,4,4,8,15);
}
The WindowClearRegion() call will clear the region described
by the rectangular coordinates (4,4) and (8,15).
If there is no error, WindowClearRegion() returns NO_ERROR.
If there is an error, the WindowClearRegion() function will
return the following values:
BAD_WINDOW if the WPOINTER w does not exist.
WINDOW_BOUND if the rectangular region defined is out of
bounds of the window.
WINDOW_NOT_OPEN if the window is not open for writing (use
WindowOpen() to open the window for writing).
WindowClearRegionAttr()
-----------------------
The WindowClearRegionAttr() function works the same as the
WindowClearRegion() function, except that a video attribute
is specified. Here is the prototype:
int WindowClearRegionAttr(WPOINTER w, int urow, int ucol,
int lrow, int lcol, int attr)
The attr argument is a video attribute to use to clear the
region.
Page 71 The C Window Library Page 71
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World!!",i,1);
GET_KEY();
WindowClearRegionAttr(w,4,4,8,15,REDONWHITE);
}
The WindowClearRegionAttr() call will clear the region
described by the rectangular coordinates (4,4) and (8,15)
using the video attribute defined by the constant REDONWHITE.
The WindowClearRegionAttr() returns the same values as
WindowClearRegion().
Page 72 The C Window Library Page 72
WRITING WINDOW CONTENTS TO A FILE
---------------------------------
The C Window Library allows you to print the contents of a
window using the WindowWriteTextToFile() function.
WindowWriteTextToFile()
-----------------------
The WindowWriteTextToFile() function allows you to print the
contents of a window to a file. Here is the prototype:
int WindowWriteTextToFile(WPOINTER w, char *filename,
int mode)
The first argument is the window. The second argument is the
file name. This file can be any of the DOS filenames ("con",
"prn", "aux", etc.). The file specified by filename must be
closed before calling WindowWriteTextToFile(), and the file
handle is automatically closed before exiting
WindowWriteTextToFile().
The last argument is the mode switch. If mode is 1, a
newline ('\n') is written to the file after each line of the
window is written to the file. If mode is 0, no newline
character is written.
Example:
#include "window.h"
#include <stdio.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
FILE *outfile;
char *filename = "wintext";
char *filename2 = "wintext2";
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World!!",i,1);
GET_KEY();
WindowWriteTextToFile(w,filename,1); /* use newlines */
WindowWriteTextToFile(w,filename2,0); /* no newlines */
}
Page 73 The C Window Library Page 73
The example above illustrates two calls to
WindowWriteTextToFile(). The first call writes the contents
of the window w to a file called "wintext". Note that the
mode parameter for the first call is 1. This will cause '\n'
to be written to the file for each line of the window. The
second call writes the window text to a file call "wintest2",
with the mode parameter being 0 (no '\n').
Please note that WindowWriteTextToFile() does not check if
the file already exists, so be careful that you do not
replace files that are important to you.
If there are no errors, WindowWriteTextToFile() returns
NO_ERROR.
If there are errors, WindowWriteTextToFile() will return one
of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use
WindowOpen())
FILE_CANT_OPEN if the file specified by filename cannot be
open.
FILE_CANT_CLOSE if the file specified by filename cannot be
closed.
Page 74 The C Window Library Page 74
SHADOWING WINDOWS
-----------------
With The C Window Library, you can place shadows on the
windows created. Shadows create a nice effect when displayed
with the proper background color. There are four positions
where you can place a shadow on a window: the upper left
corner of the window, the upper right corner, the lower left
corner or the lower right corner.
The shadow consists of two components. One of these
components is the part of the shadow that is drawn either on
the left or right side of the window. You can control the
width of this portion of the shadow. The other component
that makes up the shadow is the portion that is drawn either
on top of or underneath a window. You can control the height
of this portion of the shadow.
You can also control the shadows video attribute, as well as
the character that makes up the shadow itself. My suggestion
is to use ASCII character 219 for the shadow character.
Other ones that work well are ASCII 176, 178, and 178.
Transparent shadows are also supported.
You can place a shadow on a window at any time or take it off
at any time. The only restriction with the shadow is that
the window's current position must have room to draw the
shadow.
WindowDrawShadow()
------------------
The WindowDrawShadow() function places a shadow on a window.
Here is the prototype:
int WindowDrawShadow(WPOINTER w, int shadowpos, int width,
int height, int shadowchar,
int shadowattr, int transflag)
The first argument is the window that the shadow will be
drawn. The second argument is the position of the shadow.
There are four possible positions:
SHADOWUPRIGHT - draws shadow on upper right corner of the
window.
SHADOWUPLEFT - draws shadow on upper left corner of the
window.
SHADOWLOWRIGHT - draws shadow on lower right corner of
window.
SHADOWLOWLEFT - draws shadow on lower left corner of window.
Page 75 The C Window Library Page 75
The third argument is the width of the strip of the shadow
that is drawn on the right or left side of the window. The
fourth argument is the height of the strip of the shadow that
is drawn on top or underneath the window. The fifth argument
is the character to use for the shadow. The sixth argument
is the attribute to use for the shadow. The last argument is
a flag denoting whether the shadow should be a transparent
shadow. If the flag is 0, the shadow is solid, otherwise the
shadow is transparent.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue)
#define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red)
#define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
main()
{
WPOINTER w0,w1;
WindowInitializeSystem();
WindowSaveInitial(0);
w0 = WindowInitialize(NOBORDER,1,1,80,25,REVERSE,REVERSE,0);
WindowOpen(w0);
WindowDisplay(w0,1,NOEFFECT);
w1 = WindowInitialize(BORDER,5,5,40,15,BLUEONBLACK,
REDONBLACK,SINGLEBOX);
WindowOpen(w1);
WindowDrawShadow(w1,SHADOWUPLEFT,2,1,219,REVERSE,0);
WindowDisplay(w1,1,NOEFFECT);
WindowWriteString(w1,"Press a key to move shadow",1,1);
GET_KEY();
WindowDrawShadow(w1,SHADOWUPRIGHT,2,1,219,REVERSE,0);
WindowWriteString(w1,"Press a key again",2,1);
GET_KEY();
WindowDrawShadow(w1,SHADOWLOWLEFT,2,1,219,REVERSE,0);
WindowWriteString(w1,"Press a key once more",3,1);
GET_KEY();
WindowDrawShadow(w1,SHADOWLOWRIGHT,2,1,219,REVERSE,0);
GET_KEY();
WindowClose(w1,NOEFFECT);
WindowClose(w0,NOEFFECT);
}
The above example illustrates the use of WindowDrawShadow().
If there is no error, WindowDrawShadow() returns NO_ERROR.
If there are errors, WindowDrawShadow() returns one of the
following:
BAD_WINDOW if the window does not exist.
Page 76 The C Window Library Page 76
WINDOW_BOUND if a shadow could not be drawn because of window
location and the height and/or width of the shadow will
exceed the screen edges.
WindowRemoveShadow()
--------------------
The WindowRemoveShadow() function removes a shadow from a
window, and takes a single argument, namely the window
pointer. Here is the prototype:
int WindowRemoveShadow(WPOINTER w)
If there are no errors or the window does not have a shadow,
WindowRemoveShadow() returns NO_ERROR.
If there are errors, WindowRemoveShadow() returns the
following value:
BAD_WINDOW if the window does not exist.
Page 77 The C Window Library Page 77
SEE-THRU WINDOWS
----------------
You can create windows that have borders, but do not
overwrite the screen underneath. These windows are called
see-thru windows.
When creating see-thru windows the WindowMakeSeeThru()
function is used to make a defined window a see-thru window.
You can turn a non-seethru window into a seethru window and
vice-versa by calling the WindowMakeNormal() function.
WindowMakeSeeThru()
-------------------
The WindowMakeSeeThru() function turns a normal window into a
see-thru window. Here is a prototype:
int WindowMakeSeeThru(WPOINTER w)
The only argument is the window pointer. You can make a
window a see-thru window at any time, including if it is
hidden. If there is text in the normal window before making
it a see-thru window, the text is retained. If text is
written to a see-thru window, the text is written to the
window's internal write buffer, but is not displayed on the
screen.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,5,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowMakeSeeThru(w);
GET_KEY();
WindowFree(w,NOEFFECT);
}
The example above displays a normal window, and then turns
Page 78 The C Window Library Page 78
the normal window into a see-thru window when a key is
pressed.
If there are no errors, WindowMakeSeeThru() returns NO_ERROR.
If there are errors, WindowMakeSeeThru() returns the
following value:
BAD_WINDOW if the window does not exist.
WindowMakeNormal()
------------------
The WindowMakeNormal() function turns a see-thru window into
a normal text window. Any text that may have been written to
the window will be displayed. Here is the prototype:
int WindowMakeNormal(WPOINTER w)
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,5,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowMakeSeeThru(w);
GET_KEY();
WindowMakeNormal(w);
}
The example above demonstrates the WindowMakeNormal()
function.
If there are no errors, WindowMakeNormal() returns NO_ERROR.
If there are errors, WindowMakeNormal() returns the following
value:
BAD_WINDOW if the window does not exist.
Page 79 The C Window Library Page 79
MOVING AND SLIDING WINDOWS
--------------------------
With The C Window Library, you can move and slide windows on
the screen. The functions that perform this are the
WindowMove() and WindowSlide().
WindowMove()
------------
The WindowMove() function moves a window to a new location on
the screen. Here is the prototype:
int WindowMove(WPOINTER w, int row, int col)
The first argument is the window. The second and third
arguments are the row and column on the physical screen to
place the upper left hand corner of the window. Note that
row and column are screen relative coordinates, not window
relative. This is one of the few functions where row and
column denote a screen relative coordinate and not a window
relative coordinate.
If the row and/or column is out of bounds, the window is
moved as far as possible.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue)
main()
{
WPOINTER w;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,15,BLUEONBLACK,NORM,
SINGLEBOX);
WindowOpen(w);
WindowWriteString(w,"Press a key to move me",1,1);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowMove(w,12,14);
}
The example above moves the window from its original position
(1,1) to (12,14).
If there is no error WindowMove() returns NO_ERROR.
If there are errors WindowMove() returns the following value:
BAD_WINDOW if the window does not exist.
Page 80 The C Window Library Page 80
WindowSlide()
-------------
The WindowSlide() function "slides" a window from one
position on the screen to another. Here is the prototype:
int WindowSlide(WPOINTER w, int direction, int units)
The first argument is the window. The second argument tells
in which direction to move the window, either up, down, left,
or right. The constants to use for up, down, left, and right
are UP, DOWN, LEFT, and RIGHT, respectively. The third
argument tells how many rows or columns to move the window.
If the number of units will cause the window to exceed the
boundaries of the screen, the window is moved as far as
possible.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue)
main()
{
WPOINTER w;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,BLUEONBLACK,NORM,
SINGLEBOX);
WindowOpen(w);
WindowWriteString(w,"Press a key to slide right",1,1);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowSlide(w,RIGHT,20);
WindowWriteString(w,"Press a key to slide down",2,1);
GET_KEY();
WindowSlide(w,DOWN,10);
WindowWriteString(w,"Press a key to slide left",3,1);
GET_KEY();
WindowSlide(w,LEFT,20);
WindowWriteString(w,"Press a key to slide up",4,1);
GET_KEY();
WindowSlide(w,UP,20);
}
The example above illustrates how to use the WindowSlide()
function.
The return values for WindowSlide() are the same as
WindowMove().
Page 81 The C Window Library Page 81
CURSOR POSITIONING IN WINDOWS
-----------------------------
You can change the position of the cursor and its shape in
the windows you create with The C Window Library.
Cursor Maintenance in The C Window Library
------------------------------------------
As was stated before, The C Window Library can write to any
window at any time. This makes the question "which window
owns the cursor?" a hard question to answer. One method is
that the window being updated either by writing text,
clearing, etc. should have immediate control of the cursor.
The approach The C Window Library has taken is that the
top-most window always has control of the cursor. The
topmost window is determined by its rank number. Windows
with low rank numbers overlay windows with higher rank
numbers.
Creating Cursor Shapes
----------------------
The C Window Library has three pre-defined cursor shapes;
INVISIBLE, THIN, and BLOCK. An INVISIBLE cursor hides the
cursor, a BLOCK shape creates a "fat" cursor, and THIN
creates a thin cursor. If you want to define your own cursor
shapes, use the CREATE_CURSOR_SHAPE() macro. This macro
takes two arguments the first argument is the beginning scan
line, and the second argument is the ending scan line. Scan
lines determine the height of the cursor. For monochrome
systems, the scan lines range from 0 to 13. In a color
system, the scan lines range from 0 to 7. A THIN cursor has
its starting scan line at 6 and its ending scan line at 7 for
color systems, and for monochrome systems, the starting scan
line is 11 and its ending scan line is at 12. If the
starting scan line number is greater than the ending scan
line number, the cursor takes on a 'double' cursor shape.
Experiment with different starting and ending scan lines for
the desired effect.
WindowChangeCursor()
--------------------
The WindowChangeCursor() function changes the shape of the
cursor in a window. Here is the prototype:
int WindowChangeCursor(WPOINTER w, int shape)
Page 82 The C Window Library Page 82
The first argument is the window. The second argument is the
desired cursor shape.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Press a key to change cursor",1,1);
GET_KEY();
WindowChangeCursor(w,BLOCK);
WindowWriteString(w,"Press a key to change cursor again",
2,1);
GET_KEY();
WindowChangeCursor(w,INVISIBLE);
WindowWriteString(w,"Press a key to change cursor again",
3,1);
GET_KEY();
WindowChangeCursor(w,THIN);
}
If there are no errors, WindowChangeCursor() returns
NO_ERROR.
If there are errors, WindowChangeCursor() returns the
following value:
BAD_WINDOW if the window does not exist.
WindowMoveCursor()
------------------
The WindowMoveCursor() functions moves the cursor in a window
to a new location in the window. Here is the prototype:
int WindowMoveCursor(WPOINTER w, int row, int col)
Page 83 The C Window Library Page 83
The first argument is the window, and the second and third
arguments are the new (row,col) position in the window to
place the cursor.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Press a key to move cursor",1,1);
GET_KEY();
WindowMoveCursor(w,7,5);
}
If there are no errors, WindowMoveCursor() returns NO_ERROR.
If there are errors, WindowMoveCursor() returns the following
values:
BAD_WINDOW if the window does not exist.
WINDOW_BOUND if either new row or column number is out of the
boundaries of the window.
WindowGetCursorShape()
----------------------
The WindowGetCursorShape() function returns the starting and
ending scan lines of the cursor defined in a window. Here is
the prototype:
int WindowGetCursorShape(WPOINTER w, int *startline,
int *endline)
The startline and endline arguments are pointers to integers
that will contain the starting and ending scan lines of the
cursor when WindowGetCursorShape() returns.
Page 84 The C Window Library Page 84
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int startline,endline;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowGetCursorShape(w,&startline,&endline);
WindowPrintf(w,
"The starting scan line is %d\nThe ending scan line is %d",
startline,endline);
}
The example above calls WindowGetCursorShape() and uses
WindowPrintf() to print what the starting and ending scan
lines are.
If there are no errors, WindowGetCursorShape() returns
NO_ERROR.
If there are errors, WindowGetCursorShape() returns the
following values:
BAD_WINDOW if the window does not exist.
WindowGetCursorPosition()
-------------------------
The WindowGetCursorPosition() function gives the current row
and column of the cursor in a window. Here is the prototype:
int WindowGetCursorPosition(WPOINTER w, int *row, int *col)
The row and col arguments are pointers to integers that will
contain the row and column of the cursor after
WindowGetCursorPosition() is called.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
Page 85 The C Window Library Page 85
WPOINTER w;
main()
{
int row,col;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowMoveCursor(w,7,4);
WindowGetCursorPosition(w,&row,&col);
WindowPrintf(w,
"The row of the cursor is %d\n"
"The column of the cursor is %d", row,col);
}
If there are no errors, WindowGetCursorPosition() returns
NO_ERROR.
If there are errors, WindowGetCursorPosition() returns the
following value:
BAD_WINDOW if the window does not exist.
Page 86 The C Window Library Page 86
GETTING WHICH WINDOW OCCUPIES A LOCATION
----------------------------------------
You can determine the WPOINTER which occupies a location on
the screen. If you have multiple windows displayed, this can
be very useful if you have overlaps and want to know which
window is visible in a given screen location.
WindowWhich()
-------------
The WindowWhich() function determines which window is visible
on a given screen location. Here is the prototype:
WPOINTER WindowWhich(int row, int col, int page)
Note that WindowWhich() returns a WPOINTER. The arguments
row and col are absolute screen coordinates. The last
argument, page, is the video page to use when determining
which window lies in position (row,col). The WPOINTER that
is returned is the WPOINTER that occupies the specified
screen location.
#include "window.h"
WPOINTER w1, w2, w3, w4, w5;
main()
{
/* ... Assume everything including windows have been
initialized and opened */
if (WindowWhich(4,7,0) == w1)
{
/* some part of w1 is visible on row 4 column 7 of the
screen (video page 0) */
}
}
The above example calls WindowWhich to determine if w1
is visible on position (4,7) of video page 0.
Refer to the INTRODUCTION on video pages.
If there is no window visible for a given screen location,
WIN_NULL_PTR is returned. The base screen will always
return a WIN_NULL_PTR.
Page 87 The C Window Library Page 87
GETTING INPUT FROM WINDOWS
--------------------------
With The C Window Library, you can read input from windows.
The input can be simple string input, or inputting strings
with a character mask. There is also support for scrolling
input fields.
Input Manager
-------------
The input manager are functions internal in The C Window
Library that control editing, checking for invalid
characters, cursor movement, etc.
Regular Expressions
-------------------
With The C Window Library, you specify exactly what
characters are to be expected for every input position by
using a special string of characters called a regular
expression (a pattern matching string).
Note:
For those who are familiar with regular expressions, there is
a difference between the regular expressions you will see
here, and the regular expressions you will find in certain
text editors, or in computer language syntax definitions.
One major difference is that there are no wild cards denoting
an arbitrary number of repeated characters (which is usually
denoted by a '*' or a '+'), and there are no 'match begin of
string' and 'match end of string' functions.
An example of a regular expression would be the string
"[A-Z]" which means only those characters that are between A
and Z, inclusive, are to be accepted as valid input
characters. Of course, the ASCII collating sequence is used.
The following characters have special meanings in regular
expressions:
Character Purpose
--------- -------
Forward Slash (/) Removes the special meaning of the
next character in the regular
expression.
Page 88 The C Window Library Page 88
Brackets ([]) Encloses a set of characters to be
matched with the current character
entered at the keyboard. There are
other special symbols that can appear
in brackets:
-----------------------------------
Carat (^) This symbol states that
the character entered at
the keyboard must not
match any character in
the brackets. The carat
must be the first
character after the left
bracket ([), otherwise
the carat is taken
literally as just
another character.
Dash (-) Matches character
entered at keyboard with
characters in ASCII
order between
(inclusive) the
characters on either
side of the dash.
Dot (.) Matches any displayable
ASCII character.
There are two categories of regular expressions; namely
simple and complex. Simple regular expressions only specify
a single character to be entered from the keyboard, while
complex regular expressions specify that more than a single
character must be entered from the keyboard.
Here are examples of simple regular expressions:
Simple
Regular Expression What will be accepted
------------------ ---------------------
[0-9] Accept any single digit
character.
[3-7] Accept single digit character
between '3' and '7'
inclusive.
[A-Z] Accept a letter between 'A'
and 'Z' inclusive.
[A-Za-z] Accept a letter between 'A'
Page 89 The C Window Library Page 89
and 'Z' or a letter between
'a' and 'z'.
[ABCD] Accept either 'A', 'B', 'C',
or 'D'.
[A-Za-z0-9] Accept anything between 'A'
and 'Z', or 'a' and 'z', or
'0' and '9'
[0-9ABCD] Accept '0' thru '9', 'A',
'B', 'C', or 'D'.
[^A] Accept any character except
'A'.
[^A-Z] Accept any character except
the characters between 'A'
and 'Z' (inclusive).
[A-/[] Accept any character between
'A' and '[', inclusive.
Please note the use of the
forward slash to denote that
the left bracket has no
special meaning.
[A Z] Accept 'A', the space
character, or 'Z'.
[A/-Z] Accept 'A', the minus (-), or
'Z'.
[/-///]] Accept the minus (-), the
forward slash (/), or the
right bracket (]).
[!-&] Accept the ASCII characters
between '!' and '&',
inclusive.
A Accept the letter 'A'. Note
that this is equivalent to
[A].
[9] Accept the digit '9'.
. Accept any character.
[] Accept no key and call user
defined function (explained
later in the UNDEFINED
KEYSTROKE PROCESSING
section).
Page 90 The C Window Library Page 90
Remember, all of the above expressions process only one
character entered at the keyboard, even though some of the
expressions can accept a variety of characters.
As you can see there are many possibilities you can make up.
However the above forms of a regular expressions only work
for one character entered at the keyboard. What if you want
to enter a persons name, address, social security number
etc.? You can concatenate (glue together) the regular
expressions above to form a chain of regular expressions.
This resulting chain is called a complex regular expression.
Here are a few examples of complex regular expressions:
Regular Expression What will be accepted
------------------ ---------------------
[A-Z][0-9] The first character entered
must be between 'A' and 'Z'.
The second character entered
must be between '0' and '9'.
[A-Z][^A-Z][0-9] Enter three characters. The
first must be between 'A' and
'Z'. The second can be any
character except anything
between 'A' and 'Z', and the
third character must be
between '0' and '9'.
[1-9][0-9][0-9][0-9][0-9] Enter five characters. The
first must be between '1' and
'9'. The other four
characters must be between
'0' and '9'.
[A-Z][][0-9] The first character must be
between 'A' and 'Z', the
second input position calls a
user defined function
(explained in UNDEFINED
KEYSTROKE PROCESSING), and
the third character must be
between '0' and '9'.
As you can see again, the strings can get pretty long if you
wanted to setup a thirty character input specification, for
instance, a persons name. To save time typing, you can use a
multiplying factor in the regular expression. A multiplying
factor is a number that is placed before a simple regular
expression to denote that the simple regular expression is
repeated.
Here are a few examples:
Page 91 The C Window Library Page 91
Regular Expression What will be accepted
------------------ ---------------------
25[A-Z] Enter twenty-five characters. All the
characters must be between 'A' and 'Z'.
10[0-9] Enter ten characters. All must be
between '0' and '9'.
5[A-C] 3[1-3] Enter nine characters. The first five
must be between 'A' and 'C' the sixth
must be the space character, and the
last three must be between '1' and '3'.
Please note the space embedded in the
string just before the multiplying
factor 3.
[1-9]2X/[5[^A-Z]/1 Enter nine characters. The first must
be between '1' and '9'. The second and
third must be 'X'. The fourth is the
left bracket ([). The next five
characters entered can be any character
except anything between 'A' and 'Z',
and the last character to accept is a
'1'. Please note the use of the
forward slash just before the second
left bracket and just before the last
character ('1'). The forward slash
before the '1' makes sure the '1' is
not to be confused with a multiplying
factor of 1.
[A-Z]/.. Enter three characters. The first must
be between 'A' and 'Z'. The second is
the '.', and the third is any
character.
10[A-Z]3[] Enter thirteen characters. The first
ten must be between 'A' and 'Z', and
the last three input positions will
call a user defined undefined key
function (explained later in the
UNDEFINED KEYSTROKE PROCESSING
section).
The only limitation to what you can do with regular
expressions is that you cannot nest regular expressions. For
example:
[A-[A-Z]] or 20[20[a-z]]
It is ok to say [9-0] instead of [0-9]. They are both
equivalent and both accepted by The C Window Library, so
there is no need to know your ASCII table by heart, although
it is advantageous to learn it if you want to create
Page 92 The C Window Library Page 92
sophisticated regular expression strings. You can even use
the IBM extended character set (ASCII values above 127) in
the regular expression string.
Editing Input
-------------
The C library function gets(x), gets a string from the
keyboard and points the character pointer x to the string.
This function has limited editing capabilities. The only
keys recognized are the backspace, which serves as a
destructive backspace (erases character immediately to the
left) and the enter key when the user has typed in the
desired string. With The C Window Library, you have much
more editing capabilities.
The editing functions have the following default key values:
Mapped
Function Key Position
-------- --- ------
Move cursor left Left Arrow 0
Move cursor right Right Arrow 1
Delete character at cursor Del (on keypad) 2
Toggle Insert/Overwrite mode Insert (on keypad) 3
Erase Input and go to first column ^E 4
Destructive backspace Backspace 5
Accept Input and return Enter 6
Accept default and return Escape 7
Go to first column Home 8
Move cursor to last char. entered End 9
Here is a list of what the key functions perform:
Move cursor left - Moves the cursor left one character. If
the beginning of the input field is
encountered the cursor is not moved.
Move cursor right - Moves the cursor right one character. If
the end of the input field is
encountered, the cursor is not moved.
Delete character at cursor - Deletes the character at the
position of the cursor. If in
insert mode, any input to the
right of the cursor is moved one
character to the left. If in
overwrite mode, no characters
are moved.
Toggle Insert/Overwrite Mode - toggles the input between
insert and overwrite mode. If
Page 93 The C Window Library Page 93
in insert mode, the default
cursor is an underline cursor.
If in overwrite mode, the
default cursor is a full
block.
Erase Input - Deletes all characters inputted and moves the
cursor to the first input position.
Destructive Backspace - deletes the character immediately to
the left of the cursor and moves the
cursor to the left one character. If
insert mode is on, the characters
from the current cursor position to
the end of the input field are also
moved.
Accept string - Accepts the string that is inputted and
returns the string.
Accept default and return - Returns the default string given
to the input routine.
Go to first column - Moves cursor to the first input
position.
Go to last character - Moves cursor to the last character in
the current input string.
The keys used to perform these functions can be changed. The
mapped position is the offset in a table of key functions.
By changing the value there, you can change the key used to
perform these functions. If you do want to change these
keys, I recommend using the key definitions found in the
keycodes.h file. For example, if you wanted Control-B to be
the destructive backspace you would do as follows:
window_edit_key[5] = CTRLB;
The table of key functions is stored in the array
window_edit_key. The CTRLB stands for Control-B and its
definition is found in the keycodes.h file. To totally
undefine a key definition, assign a 0 to the desired array
position in window_edit_key. For example:
window_edit_key[2] = 0;
undefines the delete character at cursor definition.
When changing keys, make sure that the definitions all have
unique key combinations. If you desire more keystrokes for a
particular key function, see Undefined Keystroke Processing
below.
Page 94 The C Window Library Page 94
Last Key Value
--------------
On exit of any of the input functions, the global integer
last_key_hit contains the ascii code (scan code) of the key
that was used to exit the input function.
Default Cursor Types and Editing Mode
-------------------------------------
By default, The C Window Library starts editing input in
overstrike mode. This means that characters are overwritten
when the cursor is placed on a character. The opposite of
overstrike mode is insert mode, which pushes the characters
to the right of the cursor over by one input position when a
character is entered. Also, the default cursor type for
overstrike mode is a block cursor, and the default cursor for
insert mode is a thin cursor. You can change the startup
mode, as well as the cursor types.
The global variables default_cursor_type and
default_cursor_mode store the values of the cursor shapes and
the startup mode.
The default_cursor_type is an array of two integers. The
OVERSTRIKEMODE constant is the position in the
default_cursor_type array of where the overstrike shape of
the cursor is stored. The INSERTMODE constant is the
position in default_cursor_type of where the insert shape of
the cursor is stored. Here is an example of how you would
change the cursor types.
#include "window.h"
main()
{
WindowInitializeSystem();
/*...*/ /* Some code */
default_cursor_type[OVERSTRIKEMODE] =
CREATE_CURSOR_SHAPE(6,7);
default_cursor_type[INSERTMODE] = THIN;
}
The CREATE_CURSOR_SHAPE() macro creates a cursor shape by
using the first argument as the starting scan line of the
cursor, and the second argument as the ending scan line.
Refer to VIDEO MACROS section for more information on
CREATE_CURSOR_SHAPE(). The THIN constant is a predefined
constant that stands for a thin cursor. The other predefined
constants for cursor shapes are BLOCK and INVISIBLE.
To change the startup mode when an input function is called,
Page 95 The C Window Library Page 95
you must change the default_cursor_mode global variable.
Here is how you would change the default mode:
#include "window.h"
main()
{
WindowInitializeSystem();
/*...*/ /* Some code */
default_cursor_mode = OVERSTRIKEMODE;
}
Use the constants OVERSTRIKEMODE and INSERTMODE for the
desired mode.
Editing using a character mask
------------------------------
The C Window Library also provides input functions that use
character masks. For example to enter a date, you might want
the user to enter a date in MM-DD-YY format. Instead of the
user having to enter the hyphens, it would be advantageous if
the input field already had hyphens, and the cursor will
advance or back up to the next input position, jumping over
any hyphens encountered. You can accomplish this by using a
character mask.
The mask is a character string which is made up of
displayable characters, and a special character used to
denote an input position. For example, a date mask would
look like this:
__-__-__
The hyphens are displayed in the window, but the underscores
are not displayed. The underscores are used as a place
holder, i.e. a place where input is expected. By default,
the input position character is an underscore, but you can
change this. Another example would be a social security
mask:
___-__-____
a telephone mask:
(___) ___-____ ext: ____
another date mask:
__/__/__
If a character is deleted or inserted, the input manager is
smart enough to move characters so that they do not clobber
the characters that are not part of the input field.
Page 96 The C Window Library Page 96
Editing Functions
-----------------
The following are functions that can be used to edit input
with The C Window Library.
WindowGetString()
-----------------
The WindowGetString() function gets a string from a window
starting at a certain row and column of the window. Here is
the prototype:
int WindowGetString(WPOINTER w, int row, int col,
char *buffer, int fillchar, int minchars,
int maxwidth, int options, int startpos,
char *regexp)
The first argument is the window pointer. The second and
third arguments are the row and column of where the input
begins. The fourth argument is a pointer to a character
buffer where the input characters will be stored. Whatever
null terminated string is stored in the character buffer
prior to calling WindowGetString() will be used as a default
string. For example:
strcpy(str,"ABC");
WindowGetString(w,2,1,str,' ',3,3,0,"3[A-Z]");
The default value of "ABC" will be displayed in the window
when WindowGetString() is called. Therefore, make sure that
your string buffer has a 0 in the 0th position if you want to
make sure your input is empty when WindowGetString() is
called. When inputting information, hitting the Escape key
(or whatever the current key definition is for
window_edit_key[7]) will abort input and will return the
original default string.
The fifth argument is the fill character. This character is
used to fill any unfilled input positions on the window.
Instead of having spaces for unfilled positions, you can have
any character. Try ASCII 177 or the underline character.
You may like the effect.
The sixth argument is the minimum number of characters to
accept. If the number of characters entered is less than
minchars, the input manager will not accept the input.
However, you can change this by allowing the input manager to
call a user defined routine when it detects that the minimum
number of characters was not satisfied. More information on
this later in this section.
Page 97 The C Window Library Page 97
The seventh argument is the maximum width of the displayable
input field. This argument allows for scrollable input
fields. If the maximum width of the displayable field is
less than the total number of characters in the input field,
the field will scroll right and left depending on the input
position. If the input cursor exceeds the right edge of the
displayable field, the input is scrolled right until the next
input position is visible. If the cursor is moved beyond the
left edge of the displayable field, the input is scrolled
left until the previous input position comes into view.
Scrolling input fields allow for large input fields in small
windows.
The eighth argument is an integer representing the various
options available for the input field. The various options
available will be discussed later on.
The ninth argument is the starting position in the input
string of where the cursor will be placed. Position numbers
start from 1 to the maximum number of input positions. For
most applications, the starting position is usually 1. If
the starting position is not within bounds of the input
string, the starting position is assumed to be 1.
The last argument is the regular expression to use for the
input. Make sure that the input buffer you provide is large
enough to hold the maximum number of characters plus one more
character for the terminating null character.
More Examples:
WindowGetString(w,2,1,str,' ',1,1,NO_OPTIONS,1,"[YyNn]");
This will accept one character but only if the character is
'Y','y','N', or 'n'. Another example is this:
WindowGetString(w,2,1,str,' ',5,5,NO_OPTIONS,1,"5[0-9]");
This will allow the user to enter five digit characters.
To accept all characters, use this:
WindowGetString(w,2,1,str,' ',3,3,NO_OPTIONS,1,".");
Example Program:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
Page 98 The C Window Library Page 98
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is NULL */
WindowWriteString(w,"Enter Your first name :",1,1);
WindowGetString(w,2,1,buffer,' ',0,40,NO_OPTIONS,1,"40.");
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
GET_KEY();
WindowWriteString(w,"Now Enter your last name:",6,1);
/* Note that the last string is now used as a default */
WindowGetString(w,7,1,buffer,' ',0,40,NO_OPTIONS,1,"40.");
WindowWriteString(w,"You entered the following:",8,1);
WindowWriteString(w,buffer,9,1);
}
If there are no errors, WindowGetString() returns NO_ERROR.
If there are errors, WindowGetString() returns the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use
WindowOpen())
NO_HEAP_MEM if there is not enough memory to allocate for
internal buffers.
NO_INPUT_CHARS if the regular expression indicates no
characters to accept.
WindowGetStringAttr()
---------------------
The WindowGetStringAttr() function is the same as the
WindowGetString() function described above except that a
video attribute is used for the input entered. Here is the
prototype:
int WindowGetStringAttr(WPOINTER w, int row, int col,
char *buffer, int fillchar,
int minchars, int maxwidth,
int options, int startpos, int attr,
char *regexp)
Page 99 The C Window Library Page 99
Note that attr is the tenth argument. This is the video
attribute to use when receiving input.
Example Program:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is NULL */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter Your first name :",1,1);
WindowGetStringAttr(w,2,1,buffer,' ',0,40,NO_OPTIONS,1,
REVERSE,"40.");
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
GET_KEY();
WindowWriteString(w,"Now Enter your last name:",6,1);
/* Note that the last string is now used as a default */
WindowGetStringAttr(w,7,1,buffer,' ',0,40,NO_OPTIONS,1,
REVERSE,"40.");
WindowWriteString(w,"You entered the following:",8,1);
WindowWriteString(w,buffer,9,1);
}
The return values for WindowGetStringAttr() are the same as
WindowGetString().
WindowGetMaskString()
---------------------
The WindowGetMaskString() function is the same as the
WindowGetString() except that a character mask is used when
editing the input. Here is the prototype:
int WindowGetMaskString(WPOINTER w, int row, int col,
char *buffer, char *mask,
int fillchar, int minchars,
int maxwidth, int options,
int startpos, char *regexp)
Page 100 The C Window Library Page 100
The mask argument is an extra argument. This is the
character mask to use when editing the input. The string
returned in the buffer does not contain any characters that
are used for the mask. For instance, if the mask is
"__/__/__", and the string entered is "121589",
WindowGetMaskString() will place "121589" into the buffer.
If you want to create a string with the components separated
according to a mask pattern, use the
TranslateStringToMaskString() function described later in the
manual. Default strings must be set up 'unmasked'. For
instance, if you wanted the default date to be "12/15/89",
and the character mask is "__/__/__", your string buffer
should contain "121589" before calling WindowGetMaskString().
This same rule applies to any input functions that use a
character mask.
Example:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define TELMASK "(___)___-____ ext:____"
#define SSMASK "___-__-____"
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter Your Telephone No.",1,1);
WindowGetMaskString(w,2,1,buffer,TELMASK,' ',0,40,
NO_OPTIONS,1,"40.");
WindowWriteString(w,"You entered the following phone no:",
3,1);
WindowWriteString(w,buffer,4,1);
GET_KEY();
memset(buffer,0,sizeof(buffer));
WindowWriteString(w,"Now Enter your Soc. Sec. Number:",
6,1);
WindowGetMaskString(w,7,1,buffer,SSMASK,' ',0,40,
NO_OPTIONS,1,"40.");
WindowWriteString(w,"You entered the following:",8,1);
WindowWriteString(w,buffer,9,1);
}
If there are no errors, WindowGetMaskString() returns
NO_ERROR.
Page 101 The C Window Library Page 101
If there are errors, WindowGetMaskString() returns the
following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use
WindowOpen())
NO_HEAP_MEM if there is not enough memory to allocate for
internal buffers.
WindowGetMaskStringAttr()
-------------------------
The WindowGetMaskStringAttr() functions works the same way as
WindowGetMaskString() except that WindowGetMaskStringAttr()
allows you to specify a video attribute to use for the
characters that are entered. Here is the prototype:
int WindowGetMaskStringAttr(WPOINTER w, int row, int col,
char *buffer, char *mask,
int fillchar, int minchars,
int maxwidth, int options,
startpos, int attr, char *regexp)
Example:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
#define TELMASK "(___)___-____ ext:____"
#define SSMASK "___-__-____"
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter Your Telephone No.",1,1);
WindowGetMaskStringAttr(w,2,1,buffer,TELMASK,' ',0,40,
NO_OPTIONS,1,REVERSE,"40.");
WindowWriteString(w,"You entered the following phone no:",
3,1);
WindowWriteString(w,buffer,4,1);
Page 102 The C Window Library Page 102
GET_KEY();
memset(buffer,0,sizeof(buffer));
WindowWriteString(w,"Now Enter your Soc. Sec. Number:",6,1);
WindowGetMaskStringAttr(w,7,1,buffer,SSMASK,' ',0,40,
NO_OPTIONS,1,REVERSE,"40.");
WindowWriteString(w,"You entered the following:",8,1);
WindowWriteString(w,buffer,9,1);
}
The return values for WindowGetMaskStringAttr() are the same
as WindowGetMaskString().
Getting Passwords
-----------------
The C Window Library also allows you to receive hidden input.
The functions to perform this are WindowGetPassword(),
WindowGetMaskPassword(), WindowGetPasswordAttr() and
WindowGetMaskPasswordAttr(). These functions are similar to
the other WindowGetxx() functions. except that a character
specified by you is displayed instead of the actual key
pressed.
WindowGetPassword()
-------------------
The WindowGetPassword() function gets hidden input from a
window. Here is the prototype:
int WindowGetPassword(WPOINTER w, int row, int col,
char *buffer, int fillchar,
int passchar, int minchars,
int maxwidth, int options,
int startpos, char *regexp)
The first argument is the window pointer. The second and
third arguments are the (row,col) to start receiving input.
The fourth argument is the buffer to store the inputted
characters. The fifth argument is the character to use to
fill empty input positions on the screen. The sixth argument
is the character to display to the screen when a key is
pressed. The last four arguments are the same as the
WindowGetString()'s last four arguments.
For example, if the user typed "ABCDEF", and the passchar is
'*', the screen will display "******". Notice the asterisk
is displayed instead of the actual characters inputted.
Example Program:
#include "window.h"
#include <string.h>
Page 103 The C Window Library Page 103
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter A Password",1,1);
WindowGetPassword(w,2,1,buffer,' ','*',0,40,NO_OPTIONS,
1,"40.");
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
}
The return values for WindowGetPassword() are the same as
WindowGetMaskString().
WindowGetPasswordAttr()
-----------------------
The WindowGetPasswordAttr() function is the same as
WindowGetPassword() except that a video attribute is
specified for the input characters. Here is the prototype:
int WindowGetPasswordAttr(WPOINTER w, int row, int col,
char *buffer, int fillchar,
int passchar, int minchars,
int maxwidth, int options,
int startpos, int attr,
char *regexp)
Please note that the attribute argument is the next to last
argument in the function.
Example Program:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
char buffer[80];
Page 104 The C Window Library Page 104
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter A Password",1,1);
WindowGetPasswordAttr(w,2,1,buffer,' ','*',0,40,
NO_OPTIONS,1,REVERSE,"40.");
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
}
The return values for WindowGetPasswordAttr() are the same as
WindowGetMaskString().
WindowGetMaskPassword()
-----------------------
The WindowGetMaskPassword() function works just like
WindowGetPassword() except that a character mask is supplied.
Here is the prototype:
int WindowGetMaskPassword(WPOINTER w, int row, int col,
char *buffer, char *mask,
int fillchar, int passchar,
int minchars, int maxwidth,
int options, int startpos,
char *regexp)
Example:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define CREDITCARDMASK "____-____-____-____"
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
Page 105 The C Window Library Page 105
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter A Credit Card #",1,1);
WindowGetMaskPassword(w,2,1,buffer,CREDITCARDMASK,' ','*',
0,40,NO_OPTIONS,1,"40.");
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
}
The return values for WindowGetMaskPassword() are the same as
WindowGetMaskString().
WindowGetMaskPasswordAttr()
---------------------------
The WindowGetMaskPasswordAttr() function works just like
WindowGetMaskPassword() except that a video attribute is
supplied. Here is the prototype:
int WindowGetMaskPasswordAttr(WPOINTER w, int row, int col,
char *buffer, char *mask,
int fillchar, int passchar,
int minchars, int maxwidth,
int options, int startpos,
int attr, char *regexp)
Example:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
#define CREDITCARDMASK "____-____-____-____"
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter A Credit Card #",1,1);
WindowGetMaskPasswordAttr(w,2,1,buffer,CREDITCARDMASK,' ',
'*',0,40, NO_OPTIONS,1,REVERSE,
"40.");
Page 106 The C Window Library Page 106
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
}
The return values for WindowGetMaskPasswordAttr() are the
same as WindowGetMaskString().
Undefined Keystroke Processing
------------------------------
Another powerful feature of the input functions is that you
can call a function for keys that are not in the current key
definitions. For instance, say you want the Enter key AND
Control-R to mean accept the input. Since there is only room
for one definition for accept input, you can write a function
that checks for the Control-R key, and return a number to the
input manager as to what action to take.
The undef_fkey_func and undef_akey_func function pointers
---------------------------------------------------------
There are two global variables, undef_fkey_func and
undef_akey_func. Both of these function pointers are defined
in the file key.h. These two variables are pointers to
functions that return an integer. By setting these functions
to point to your own functions, you can process undefined
keystrokes yourself and return to the input manager what
action to take.
The undef_fkey_func is used to define keys that are not
normal ASCII keys. For instance, Control key and Alt key
combinations, the F-keys, PgDn and PgUp, etc. The
undef_akey_func is used to define normal ASCII keys (keys
with ASCII values between 32 and 255, inclusive).
Whenever an undefined key is encountered, the input manager
will pass the string that has been currently entered, the
current key pressed, the current position number of the
character being processed, and a pointer to a new position to
place the input cursor. The prototype for this function is
as follows:
int (*undef_fkey_func)(char *str,int key,
int pos,int *newposptr)
The prototype to the undef_akey_func is similar to the one
above.
The str is a pointer to a null-terminated string of
characters that has been currently entered. For instance, if
Page 107 The C Window Library Page 107
the string currently entered is
ABC123
str will point to "ABC123".
The second argument is the last key that was pressed. You
should use the values defined in the header file "keycodes.h"
if you want to check for non-ascii keys. This will ensure
that you are properly checking the keystroke desired. For
instance, if you want to check if the key pressed was the
Page Up key, use the constant PGUP defined in keycodes.h.
The third argument is an integer representing the position
number of the current character that the cursor is on. The
first character is at position number 0, the second character
in the input field is 1, etc. If there is an input mask (as
in WindowGetMaskString() and WindowGetMaskStringAttr()) the
position number does not include any characters that are used
to create the non-input positions. For instance:
"__/__/__ "
01 23 45
The numbers under the mask are the position numbers for each
character.
The fourth argument is a pointer to an integer representing a
new position to move the cursor. Use of this pointer will be
explained later. for this argument will be made evident
later. The reason for the third argument being a pointer
rather than an integer will be evident later on.
Specifying when to call an undefined key function in a
Regular Expression
-------------------------------
An empty bracketed simple regular expression tells the input
manager to call the undefined keystroke function. An example
of this type of regular expression is as follows:
Regular Definition
Expression ----------
----------
[A-Z][] The first input position must
be btween 'A' and 'Z', and
the second position will
automatically call the user
defined undefined keystroke
function.
20[] All twenty input positions
Page 108 The C Window Library Page 108
will call the undefined
keystroke function.
3[0-9]2[]2[A-Z] The first three input
positions must be between '0'
and '9', the next two input
positions automatically call
the undefined keystroke
function, and the last two
positions must be between 'A'
and 'Z'.
If you use this form of a regular expression, you MUST have
defined an undefined keystroke function. If you did not
define one, you will more than likely get into an infinite
loop. Using this form of regular expression combined with
the return values (defined below) that can be returned to the
input manager, you will virtually have total control of the
way the input is handled.
Return Values To The Input Manager
----------------------------------
When writing your function you must return an integer to the
input manager. This integer will inform the input manager as
to what action to take. Here are a list of the return values
and what they inform the input manager:
Return Action to
Value Take
------ ---------
DONT_PROCESS Do not Process keystroke and
continue getting input.
MOVE_CURSOR_LEFT Move cursor left.
MOVE_CURSOR_RIGHT Move cursor right.
DELETE_AT_CURSOR Delete character at cursor.
TOGGLE_INSERT Toggle Insert/Overwrite mode.
DESTRUCT_BACKSPACE Destructive Backspace.
ACCEPT_INPUT Accept Input and return string.
ACCEPT_DEFAULT Accept default string and return.
ERASE_INPUT Erase Input and go to first
Page 109 The C Window Library Page 109
character in input field.
GOTO_FIRST Go to first input character in
field.
GOTO_LAST Move cursor to last input character
in field.
MOVE_TO_CHARACTER Move cursor to input position
specified in the *pos argument.
INSERT_CHARACTER Accept character as valid and insert
it at the current cursor position.
The MOVE_TO_CHARACTER return value moves the input cursor to
the position in the input string specified in the fourth
argument of undef_akey_func or undef_fkey_func. If you
recall, the fourth argument was a pointer to an integer.
The INSERT_CHARACTER return value only applies to the
function pointed to by undef_akey_func.
These user-defined functions can do anything, not just
process keystrokes. For instance, if you want F1 to be a
help key, where the help function is in a function called
do_help() you must make sure that:
a) the F1 key is undefined (not defined in the
window_edit_key array) b) the undef_fkey_func function
pointer points to your function c) return an integer to the
input manager from your function.
Here is a typical way that this would be set up:
#include "window.h"
/* ... Other #includes and #defines */
int do_help(); /* define help function */
main()
{
WindowInitializeSystem();
/* ...Some code */
undef_fkey_func = do_help;
WindowGetString(/* ... Parameters */);
/* ... Other code */
}
Page 110 The C Window Library Page 110
int do_help(char *str, int ch, int pos, int *newpos)
{
if (ch == F1) /* check for F1 */
{
/* help function goes here */
return DONT_PROCESS; /* make sure input manager does not
process this or any other
undefined keystroke */
}
else
{
*newpos = 3; /* move input cursor to the third
input position */
return MOVE_TO_CHARACTER /* let input manager know we
want to move the input
cursor */
}
}
With this flexibility in the input functions, you can totally
control how input is handled.
Page 111 The C Window Library Page 111
Input Options
-------------
In the previous examples, the available options were
discussed briefly. These options provide further control of
the input functions. Here is a list of the options that are
available:
Option Definition
------ ----------
UPPERCASE Translates and displays lower
case to upper case.
LOWERCASE Translates and displays upper
case to lower case.
CHECKSPACES Spaces are counted when
determining whether the minimum
number of characters are
entered.
ENHANCEDKEY Use the enhanced keyboard keys
and distinguish between keypad
keys and separate cursor pad
keys. Also detect F11 and F12
keys.
CHECKREGEXP Check to see if all characters
entered agree with the regular
expression provided.
AUTORETURN Automatically accept the input
when a character in the last
input position is entered.
HOMECURSOR Move scrolled input back to the
first character in the input
string when input is accepted.
CLEARFIELD Clears the input field if the
first key pressed is recognized
by the regular expression as a
valid input key. If a cursor
movement key is pressed first,
the field is not cleared if any
subsequent input keys are
pressed.
USEMOUSE Utilize the mouse to move the
cursor in the input field.
NO_OPTIONS No options desired.
Page 112 The C Window Library Page 112
UPPERCASE
---------
The UPPERCASE option converts and displays all lower case
letters to upper case while the user is inputting characters.
LOWERCASE
---------
The LOWERCASE option converts and displays all upper case
letters to lower case while the user is inputting characters.
CHECKSPACES
-----------
The CHECKSPACES option will cause the input manager to count
any embedded spaces when determining whether the minimum
number of characters are reached. Trailing spaces are
counted only if the user explicitly put them there.
ENHANCEDKEY
-----------
The ENHANCEDKEY option will distinguish between the cursor
keys on the keypad from the dedicated cursor keys on the
enhanced keyboards as well as the Ins, Home, Del, PgUp and
PgDn keys. Also the F11 and F12 keys will be detected.
CHECKREGEXP and the reg_exp_error_func function pointer
-------------------------------------------------------
The CHECKREGEXP option will check to make sure that every
character inputted is a valid character according to the
regular expression. When inserting or deleting characters
during input, characters may be moved left or right depending
on whether the input is in insert or overwrite mode. When
the characters are moved, the resulting pattern of characters
may not match the regular expression desired. For instance,
if the regular expression is "3[A-Z]2[0-9]", meaning 3
characters between A and Z followed by 2 characters between 0
and 9, and the current input entered is as follows :
ABC34
If the cursor is currently under the 'C', the delete key is
pressed, and the input is currently in insert mode, the '34'
will be moved one character to the left. The resulting input
would then look like this:
AB34
As you can see, the input does not match the regular
Page 113 The C Window Library Page 113
expression "3[A-Z]2[0-9]" because the '3' is in a position
that should be occupied by a letter. When the CHECKREGEXP
option is chosen, each position is checked when the user
wants to accept the string, not while the user is entering
characters. If the input is not OK, the input manager will
not accept the string. You can override this by setting the
reg_exp_error_func function pointer.
The global function pointer reg_exp_error_func is prototyped
as follows:
int (*reg_exp_error_func)(char *buf, int nomatch);
where buf is the current string entered, and nomatch is the
position of the first non-matching character that did not
match the regular expression. The first character of the
string is at position 0.
Your function must return an integer back as to what to do.
There are two valid return values, namely ACCEPT_INPUT and
DONT_PROCESS. A return value of ACCEPT_INPUT will accept the
input, even though all of the characters do not match the
regular expression. DONT_PROCESS tells the input manager to
keep getting input. Here is an example:
int my_check_func();
main()
{
...
reg_exp_error_func = my_check_func;
WindowGetString(other parameters, CHECKREGEXP,
"[A-Z][0-9]");
...
}
int my_check_func(char *buf, int mistake_pos)
{
/* Assume w is initialized and open for writing */
WindowPrintf(w,
"Illegal input for %s. Illegal character at position %d",buf,
mistake_pos);
GET_KEY();
WindowHide(w,NOEFFECT);
return DONT_PROCESS;
}
The above example shows a function called my_check_func()
which will be called when the input manager detects that all
of the characters in the buffer buf do not match the regular
Page 114 The C Window Library Page 114
expression. The function displays a message in a window and
waits for a key to be pressed. Then the function returns
DONT_PROCESS back to the input manager.
AUTORETURN
----------
The AUTORETURN will automatically accept the input and return
to the calling function if the cursor is on the last input
position and the user types a valid character. Of course, if
CHECKREGEXP is on, the input is checked for validity.
HOMECURSOR
----------
The HOMECURSOR options will scroll an input field back to the
first position when the input is accepted.
CLEARFIELD
----------
The CLEARFIELD option will automatically clear the input
field of any characters if the first key struck is a key
recognized as a valid input key, and the character is
displayed in the input position. If the first key struck is
a cursor movement key or a delete character key (destructive
backspace or delete character), any valid input key that is
subsequently struck does not clear the field, but is
recorded in the input field.
USEMOUSE
--------
This option can only be used if you have access to The C
Window Library MouseLib functions, the system has a mouse
installed, and the mouse has been activated. By positioning
the mouse cursor to any valid input position in the input
field and pressing the mouse button defined in the global
integer variable field_button_press, the cursor is
automatically moved to that input position. If the
CLEARFIELD option is used in conjunction to USEMOUSE, any
subsequent input will not clear the field if the mouse was
used to move the cursor.
NO_OPTIONS
----------
No field options desired. In other words, all of the options
defined above are turned off.
Page 115 The C Window Library Page 115
Examples of Input Options
-------------------------
Examples:
a) WindowGetString(w,1,1,str,' ',1,1,UPPERCASE,"[YyNn]");
b) WindowGetString(w,1,1,str,' ',1,1,LOWERCASE,"[YyNn]");
c) WindowGetStringAttr(w,2,1,str,' ',
CREATE_VIDEO_ATTRIBUTE(black,white),1,
1,UPPERCASE | AUTORETURN,"[YyNn]");
d) WindowGetString(w,1,1,str,' ',10,10,
UPPERCASE | ENHANCEDKEY,"10.");
e) WindowGetString(w,1,1,str,' ',20,10,CHECKREGEXP |
HOMECURSOR,"10[A-Z]10[0-9]");
Example a) gets one character and will automatically set this
character to upper case.
b) same as a) except character is converted to lower
case.
c) converts one character to uppercase and
automatically accepts the input because the input
cursor was on the last input position. Note the
use of the bitwise OR (|) to set multiple options.
d) Converts the input to uppercase and treats extra
keys on an enhanced keyboard as different than
their "normal" keys.
e) On accepting of the input field, the input is
checked to see if every position on the input
field is checked to see if it matches the regular
expression. Once the input is accepted, the input
is scrolled back to the first input position.
THE num_chars_entered_func FUNCTION POINTER
-------------------------------------------
If the number of characters entered is not enough to satisfy
the minimum number of characters allowed, by default the
input manager will not return until the required number of
characters is entered. However, a global function pointer
can be assigned to a user-written function that will be
called when the input manager detects that the minimum number
of characters was not reached. The function pointer
num_chars_entered_func is prototyped as follows:
Page 116 The C Window Library Page 116
int (*num_chars_entered_func)(char *buf, int minchars);
where buf is the current string that is entered, and minchars
is the minimum number of characters to expect.
Your function must return an integer back as to what to do.
There are two valid return values, namely ACCEPT_INPUT and
DONT_PROCESS. A return value of ACCEPT_INPUT will accept the
input, even though the minimum number of characters was not
reached. DONT_PROCESS tells the input manager to keep
getting input. Here is an example:
int my_min_func();
main()
{
...
num_chars_entered_func = my_min_func;
...
}
int my_min_func(char *buf, int m)
{
/* Assume w is initialized and open for writing */
WindowWriteString(w,"Not enough characters!",1,1);
GET_KEY();
WindowHide(w,NOEFFECT);
return DONT_PROCESS;
}
The above example shows a function called my_min_func() which
will be called when the input manager detects that the number
of characters in the buffer buf, does not meet the minimum
requirements. The function displays a message in a window
and waits for a key to be pressed. Then the function returns
DONT_PROCESS back to the input manager.
Other Input Related Functions
-----------------------------
There are other input related functions that you can use to
translate strings into their character mask equivalents and
vice-versa.
TranslateStringToMaskString()
-----------------------------
This TranslateStringToMaskString() function takes a string
Page 117 The C Window Library Page 117
and either places spaces, or the actual mask character
between the characters in the string. A pointer to the
translated string is returned. Here is the prototype:
char *TranslateStringToMaskString(char *buffer, char *mask,
char *buf2, int maskchar,
int flag)
The first argument is a pointer to the string to translate.
The second argument is the mask string to use. The third
argument is a pointer to the buffer that will store the
translated string. The fourth argument is the mask character
that is to be used. This character determines where the
input positions are. The flag argument tells whether to
include spaces between each component, or to use the
character in the mask.
You must make sure that buf2 is big enough to hold the
translated string.
The string length of the mask determines how far to translate
the string. If the mask string is shorter than the string to
translate, the string is truncated up to the last character
in the mask. If the string to translate runs out of
characters before the mask has been totally scanned, the
extra characters in buf2 will either be spaces, or the
characters in the mask (not the mask character specified in
argument 4) will be copied over.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define DATEMASK "__/__/__"
char buf1[] = "123456";
char buf2[9];
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,
SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
TranslateStringToMaskString(buf1,DATEMASK,buf2,'_',0);
WindowPrintf(w,
"The original string is %s\nThe translated string is %s\n",
buf1,buf2);
TranslateStringToMaskString(buf1,DATEMASK,buf2,'_',1);
WindowPrintf(w,
"The original string is %s\nThe translated string is %s\n",
buf1,buf2);
}
Page 118 The C Window Library Page 118
The example above takes the string "123456" with the mask of
"__/__/__". The results of a translate with a flag of 0, and
with a flag value of 1, is displayed in window w.
The return value for TranslateStringToMaskString() is the
pointer to the buffer that holds the translated string. This
string is automatically null terminated.
TranslateMaskStringToString()
-----------------------------
This TranslateMaskStringToString() function does the opposite
of TranslateStringToMaskString(). This function takes a
string that has been translated with the
TranslateStringToMaskString() or contains mask characters and
returns the string without the extra characters. Here is the
prototype:
char *TranslateMaskStringToString(char *buffer, char *mask,
char *buf2, int maskchar)
The first argument is a pointer to the translated string.
The second argument is the mask string to use. The third
argument is a pointer to the buffer that will store the
resulting string. The fourth argument is the mask character
that is to be used. This character determines where the
input positions are.
You must make sure that buf2 is big enough to hold the new
string.
The translation stops when either the end of the buffer is
reached, or the end of the mask string is reached.
Example:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define DATEMASK "__/__/__"
char buf1[] = "12/34/56";
char buf2[9];
WPOINTER w;
main()
{
memset(buf2,0,sizeof(buf2));
WindowInitializeSystem();
Page 119 The C Window Library Page 119
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
TranslateMaskStringToString(buf1,DATEMASK,buf2,'_');
WindowPrintf(w,"The original string is %s\n"
"The untranslated string is %s\n", buf1,buf2);
}
The example above takes the string "12/34/56" with the mask
of "__/__/__". The results of the translation is displayed
in window w.
The return value for TranslateMaskStringToString() is the
pointer to the buffer that holds the translated string. This
string is automatically null terminated.
Page 120 The C Window Library Page 120
VIRTUAL WINDOWS
---------------
A virtual window can be thought of as a rectangular area
filled with text. This rectangular region can be broken up
into rows and columns, just as a normal window can be divided
into rows and columns. The differences between a virtual
window and a regular window is that a virtual window's
dimensions can be larger than the physical screen, and a
virtual window is not displayed on the screen. Then what
good is it if you cannot display it? You use regular windows
to display portions of the virtual window. If a regular
window is used to view a virtual window, the regular window
is called a viewport. With this method, you can use a
viewport to display a virtual window, and then 'pan' around,
viewing different sections of the virtual window. Text
editors use this method to display files. Scrolling popup
menus also use virtual windows.
With The C Window Library, you can create virtual windows of
any size, up to available user memory. You can have a
maximum of 256 virtual windows defined at the same time.
Using Windows as Viewports
--------------------------
If text is written to a virtual window, and there is a
viewport that is displaying the portion of the virtual window
that has changed, the viewport will show the change
immediately. You do not have to "repaint" or "refresh" the
viewport to show an updated change. That is handled
internally in The C Window Library. However, there is an
option that will "freeze" a viewport, i.e. will not update
automatically, if there is a change in the virtual window.
When the viewport is unfrozen, the changes to the virtual
window are than displayed.
Attributed and Non-Attributed Virtual Windows
---------------------------------------------
There are two types of virtual windows. You can have either
a virtual window with its own video attributes or a virtual
window which gets its video attributes from the viewport that
is displaying the virtual window. Virtual windows without
attributes use half as much memory as a virtual window with
attributes, but attributed virtual window's are more
flexible. For instance, lets say you have highlighted some
text in the virtual window. If the virtual window is not
attributed, you must write the highlight attribute to the
viewport window using one of the window functions
Page 121 The C Window Library Page 121
(WindowWriteStringAttr() for example), since the virtual
window does not have the capacity to store the video
attribute. If you were to scroll the highlighted portion out
of the viewport, you lose the highlight attribute, and must
call the window function again to highlight the text, if the
text is displayed again in the viewport. With an attributed
virtual window, you write the attributes to the virtual
window. Since the attributes are stored in the virtual
window structure itself, the attributes are retained until
you change them.
From this point on, virtual windows without attributes are
called NOATTRIBUTE virtual windows. Virtual windows with
attributes will be called ATTRIBUTE virtual windows.
Virtual Window's Logical Cursor
-------------------------------
Each virtual window has its own logical cursor. This cursor
is updated automatically when calling VirtualPrintf(), and
VirtualWriteCharacter() functions, or can be updated manually
by calling the VirtualMoveCursor() function. This cursor is
independent of the screen cursor.
Page 122 The C Window Library Page 122
CREATING VIRTUAL WINDOWS
------------------------
The section will discuss creating virtual windows using the
VirtualInitialize() function.
VirtualInitialize()
-------------------
Virtual windows are created by calling the
VirtualInitialize() function. Here is the prototype:
VWPOINTER VirtualInitialize(int vwtype, unsigned nrows,
unsigned ncols, int attr)
The VirtualInitialize() function returns a pointer to a
virtual window structure (a VWPOINTER). The first argument
to VirtualInitialize() tells whether the virtual window will
or will not have its own video attributes. If this argument
is NOATTRIBUTE, the virtual window will not have attributes,
otherwise if it is ATTRIBUTE, the virtual window will have
its own attributes. The second argument is the number of
rows of the virtual window. The third argument is the number
of columns. The fourth argument is the attribute to use for
the virtual window. This argument is ignored if the virtual
window is NOATTRIBUTE.
Example:
#include "window.h"
#include <stdio.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw1, /* virtual window pointers */
vw2;
main()
{
WindowInitializeSystem();
/* set up a NOATTRIBUTE virtual window */
vw1 = VirtualInitialize(NOATTRIBUTE,/* virt. window type */
30, /* Number of rows */
80, /* Number of cols */
0); /* Attribute */
/* set up an ATTRIBUTE virtual window */
vw2 = VirtualInitialize(ATTRIBUTE, /* virtual window type */
30, /* Number of rows */
100, /* Number of cols */
NORM); /* Attribute */
if (vw1 == (VWPOINTER)0 ||
vw2 == (VWPOINTER)0 ) /* Check if allocation worked */
printf(
"Error in allocating virtual window."
Page 123 The C Window Library Page 123
"The error number is %d"", window_error_code);
}
In the above program, the VirtualInitialize() function is
called. This function allocates memory for the virtual
window, and does other initializations. Once this function
is called, you can write to and read characters from the
virtual window.
Notice that the first argument to VirtualInitialize() is
either the constant NOATTRIBUTE or ATTRIBUTE.
Also note that there is a check to see whether the virtual
windows could be allocated. If there are no errors,
VirtualInitialize() returns a valid VWPOINTER. If there are
errors, VirtualInitialize() returns a null VWPOINTER and sets
the global variable window_error_code to one of the
following:
NO_HEAP_MEM if there is not enough memory to allocate for the
virtual window.
MAX_V_WINDOW if there are already 256 virtual windows
defined.
Page 124 The C Window Library Page 124
ASSIGNING VIEWPORTS AND CLOSING VIEWPORTS
-----------------------------------------
For a virtual window to have any useful purpose, it should be
displayed on the screen. However the virtual window may be
larger than the physical screen. The problem is solved by
using normal windows to display parts of the virtual window.
WindowAssignToVirtual()
-----------------------
To turn a window into a viewport onto a virtual window, you
use the WindowAssignToVirtual() function.
Here is the prototype:
int WindowAssignToVirtual(WPOINTER w, VWPOINTER vw,
unsigned row, unsigned col)
The first argument is the window that will be turned into a
viewport. The second argument is the virtual window that w
will be assigned to. The third and fourth arguments are the
(row,col) of the virtual window. This position is where the
upper left hand corner of the viewport's text area will be
placed.
To illustrate this, here is a sample call to
WindowAssignToVirtual():
WindowAssignToVirtual(w,vw,5,10)
The following description shows how this is to be
interpreted:
VIRTUAL WINDOW
------------------------------------------------------------
|(1,1) 100,1)|
| |
| (5,10) of virtual window is equivalent to (1,1) of |
| | the viewport. |
| v |
| ----------------------- |
| |(1,1) of the viewport| |
| | | |
| | VIEWPORT WINDOW | |
| |(14,1) (14,30)| |
| ----------------------- |
| |
|(100,1) (100,100) |
------------------------------------------------------------
The viewport relative position of (1,1) is located at (5,10)
Page 125 The C Window Library Page 125
of the virtual window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
w = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,
SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteString(vw,"This is a string",1,1);
WindowAssignToVirtual(w,vw,1,1); /* Assign viewport
to virtual window
*/
}
The above program opens a virtual window, vw, and opens a
normal window, w. In the above example, the
VirtualWriteString() function is used to write strings to the
virtual window. See the WRITING TEXT TO VIRTUAL WINDOWS
section for more information on VirtualWriteString().
Once a window is turned into a viewport, nothing is stopping
you from using the other window functions. You can still use
WindowWriteString(), WindowMove(), WindowPrintf(), etc.
Writing text to a viewport window via the normal window
functions does not effect the virtual window in any way.
If there are no errors, WindowAssignToVirtual() returns
NO_ERROR. If there are errors, WindowAssignToVirtual()
returns the following values:
BAD_WINDOW if the window does not exist.
BAD_V_WINDOW if the virtual window does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use
WindowOpen()).
Out of bounds Coordinates
-------------------------
The next question is "What do you do if the coordinates given
in WindowAssignToVirtual() are out of bounds of the range of
the virtual window?". For instance, if the virtual window
Page 126 The C Window Library Page 126
has 100 rows, but the call to WindowAssignToVirtual()
specifies row 97, and the viewport itself has a height of 10
rows. The window manager will fill the viewport with as much
of the virtual window as possible, and will clear the
contents of the viewport that are not inside the virtual
window.
Here is another view of what happens in this case:
VIRTUAL WINDOW
----------------------------------------------------------
|(1,1) (100,1)|
| |
| (97,10) of virtual window is same as (1,1) of |
| | the viewport window. |
| v |
| ----------------------- |
| |(1,1) of the viewport| |
| | | |
|(100,1) | VIEWPORT WINDOW | (100,100) |
-----------------------------------------------------------
|This portion of the |
| window is cleared |
-----------------------
The above picture shows a viewport that is partially
contained in the virtual window. The contents of the window
above the last row of the virtual window is updated, while
the portion of the viewport below the line is cleared.
WindowCloseViewport()
---------------------
To turn a viewport back to a normal window,
WindowCloseViewport() is called. Here is the prototype:
int WindowCloseViewport(WPOINTER w, int hide, int effect)
where w is the viewport to be turned back into a regular
window. When this function is called, the window w is
cleared with its own video attribute. The second argument
tells if the window is to be hidden. If hide is 1, the window
is hidden. If it is 0, the window remains on the screen.
The effect argument is a special effect to use when hiding
the window. A list of special effects are defined in the
DISPLAYING WINDOWS section. This function DOES NOT close the
virtual window or does a WindowClose() to the viewport
window.
Page 127 The C Window Library Page 127
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
w = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteString(vw,"This is a string",1,1);
WindowAssignToVirtual(w,vw,1,1);
GET_KEY();
WindowCloseViewport(w,1,NOEFFECT);
GETKEY();
}
The example above opens a virtual windows and a normal. It
then assigns the windows to the virtual window by calling
WindowAssignToVirtual(). The program then unassigns the
viewport by calling WindowCloseViewport().
If there are no errors, WindowCloseViewport() returns
NO_ERROR. If there are errors, WindowCloseViewport() returns
the following values:
BAD_WINDOW if the window does not exist.
BAD_V_WINDOW if the virtual window that w is a viewport on
does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use
WindowOpen()).
Page 128 The C Window Library Page 128
WRITING TEXT TO VIRTUAL WINDOWS
-------------------------------
There are several functions that write strings to virtual
windows. They are divided into two groups: functions that
take null terminated strings as arguments, and functions that
use character buffers and a length argument.
When any of the text functions are called, any viewport that
is displaying any portion of the virtual window that has been
changed will display the update.
Null Terminated String Functions
--------------------------------
VirtualWriteString()
--------------------
The VirtualWriteString() function writes a null terminated to
a virtual window at a specific row and column of the virtual
window. Here is the prototype:
int VirtualWriteString(VWPOINTER vw, char *string,
unsigned row, unsigned col)
The first argument is the virtual window pointer. The second
argument is the string to write. The third and fourth
arguments are the row and column of the virtual window that
the string is to be written to. If the string will exceed
the boundaries of the virtual window, the string is
truncated.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w1, w2;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
w1 = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,
SINGLEBOX);
w2 = WindowInitialize(BORDER,13,1,20,10,NORM,NORM,
DOUBLEBOX);
WindowOpen(w1);
WindowOpen(w2);
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
VirtualWriteString(vw,"This is a string",1,1);
WindowAssignToVirtual(w1,vw,1,1);
Page 129 The C Window Library Page 129
WindowAssignToVirtual(w2,vw,1,10);
}
The example above writes the string "This is a string" to the
virtual window at row 1, column 1. The windows w1 and w2 are
viewports on the virtual window vw. The window w1 is located
at (1,1) of the virtual window, while w2 is located at (1,10)
of the virtual window. The window w1 will display "This is a
string", but w2 will only display "string" since it is
situated at column 10 of the virtual window.
If there are no errors, VirtualWriteString() returns
NO_ERROR.
If there are errors, VirtualWriteString() returns the
following values:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the either row or col is out of bounds of
the virtual window.
VirtualWriteStringAttr()
------------------------
The VirtualWriteStringAttr() works the same way as the
VirtualWriteString() except that a video attribute is used.
Here is the prototype:
int VirtualWriteStringAttr(VWPOINTER vw, char *string,
unsigned row, unsigned col,
int attr)
The last argument is the video attribute to use. If the
virtual window is NOATTRIBUTE, the attribute is ignored, and
only the string is written. Any viewports that are assigned
to NOATTRIBUTE virtual windows will not reflect the change in
the attribute.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
Page 130 The C Window Library Page 130
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,
SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteStringAttr(vw,"This is a string",1,1,REVERSE);
WindowAssignToVirtual(w,vw,1,1);
}
The example above writes the string "This is a string" in the
virtual window with a video attribute defined by the constant
REVERSE.
If there are no errors, VirtualWriteStringAttr() returns
NO_ERROR.
If there are errors, VirtualWriteStringAttr() returns the
following values:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the either row or col is out of bounds of
the virtual window.
NO_ATTRIB if the virtual window is NOATTRIBUTE. If this
error occurs, only the string is written.
VirtualWriteCenterString()
--------------------------
The VirtualWriteCenterString() writes a centered string in a
virtual window. Here is the prototype:
int VirtualWriteCenterString(VWPOINTER vw, char *string,
unsigned row)
The row argument is the row to center the string on.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
Page 131 The C Window Library Page 131
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteCenterString(vw,"This is a string",1);
WindowAssignToVirtual(w,vw,1,1);
}
The above example illustrates the use of
VirtualWriteCenterString(). The viewport window w is just
used as a guide to display what has happened.
If there are no errors, VirtualWriteCenterString() returns
NO_ERROR.
If there are errors, VirtualWriteCenterString() returns the
following values:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the row is out of bounds of the virtual
window.
VirtualWriteCenterStringAttr()
------------------------------
The VirtualWriteCenterStringAttr() function works the same
way as VirtualWriteCenterString() except that a video
attribute is specified. Here is the prototype:
int VirtualWriteCenterStringAttr(VWPOINTER vw, char *string,
unsigned row, int attr)
The attr argument is the video attribute to use. If the
virtual window is NOATTRIBUTE, the attribute is ignored and
only the string is written to the virtual window.
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
Page 132 The C Window Library Page 132
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteCenterStringAttr(vw,"This is a string",1,
REVERSE);
WindowAssignToVirtual(w,vw,1,1);
}
If there are no errors, VirtualWriteCenterStringAttr()
returns NO_ERROR.
If there are errors, VirtualWriteCenterStringAttr() returns
the following values:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the row is out of bounds of the virtual
window.
NO_ATTRIB if the virtual window is NOATTRIBUTE. If this
error occurs, only the string is written.
VirtualWriteStringCC()
----------------------
The VirtualWriteStringCC() function centers and writes a
string around a column of the virtual window (the CC stands
for Centered Column). If the string is longer than the width
of the virtual window, the string is placed on column 1 is
clipped at the right edge of the virtual window. Here is the
prototype:
int VirtualWriteStringCC(VWPOINTER vw, char *string,
unsigned row, unsigned col)
The first argument is the window. The second argument is the
string. The third argument is the row to write the string,
and the last argument is the column to center the string on.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
Page 133 The C Window Library Page 133
WindowDisplay(w,1,NOEFFECT);
VirtualWriteStringCC(vw,"This",1,10);
VirtualWriteStringCC(vw,"is",2,10);
VirtualWriteStringCC(vw,"centered",3,10);
VirtualWriteStringCC(vw,"around",4,10);
VirtualWriteStringCC(vw,"column",5,10);
VirtualWriteStringCC(vw,"10",6,10);
WindowAssignToVirtual(w,vw,1,1);
}
The example above writes the text centered around column 10
of the virtual window w.
The return values for VirtualWriteStringCC() are the same as
VirtualWriteString().
VirtualWriteStringCCAttr()
--------------------------
The VirtualWriteStringCCAttr() works the same way as the
VirtualWriteStringCC() function except that a video attribute
is specified. Here is the prototype:
int VirtualWriteStringCCAttr(VWPOINTER vw, char *string,
unsigned row, unsigned col,
int attr)
The attribute to use is the last argument. If the virtual
window is NOATTRIBUTE, the attr argument is ignored, and only
the string is written to the virtual window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteStringCCAttr(vw,"This",1,10,REVERSE);
VirtualWriteStringCCAttr(vw,"is",2,10,REVERSE);
Page 134 The C Window Library Page 134
VirtualWriteStringCCAttr(vw,"centered",3,10,REVERSE);
VirtualWriteStringCCAttr(vw,"around",4,10,REVERSE);
VirtualWriteStringCCAttr(vw,"column",5,10,REVERSE);
VirtualWriteStringCCAttr(vw,"10",6,10,REVERSE);
WindowAssignToVirtual(w,vw,1,1);
}
The return values for VirtualWriteStringCCAttr() are the same
as VirtualWriteStringAttr().
VirtualWriteStringRJ()
----------------------
The VirtualWriteStringRJ() function writes a right justified
string in a virtual window. Here is the prototype:
int VirtualWriteStringRJ(WPOINTER w, char *string,
unsigned row, unsigned col)
The first argument is the virtual window. The second
argument is the string. The third argument is the row to
write the string, and the last argument is the column to
place the right edge of the string.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,
SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteStringRJ(vw,"This",1,10);
VirtualWriteStringRJ(vw,"is",2,10);
VirtualWriteStringRJ(vw,"right",3,10);
VirtualWriteStringRJ(vw,"justified",4,10);
VirtualWriteStringRJ(vw,"on ",5,10);
VirtualWriteStringRJ(vw,"column",6,10);
VirtualWriteStringRJ(vw,"10",7,10);
WindowAssignToVirtual(w,vw,1,1);
}
The example above writes the text right justified on column
Page 135 The C Window Library Page 135
10 of the virtual window.
The return values for VirtualWriteStringRJ() are the same as
VirtualWriteString().
VirtualWriteStringRJAttr()
--------------------------
The VirtualWriteStringRJAttr() writes a right justified
string in a virtual window, and allows you to specify a video
attribute. Here is the prototype:
int VirtualWriteStringRJAttr(WPOINTER w, char *string,
unsigned row, unsigned col,
int attr)
The last argument is the attribute to use.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteStringRJAttr(vw,"This",1,10,REVERSE);
VirtualWriteStringRJAttr(vw,"is",2,10,REVERSE);
VirtualWriteStringRJAttr(vw,"right",3,10,REVERSE);
VirtualWriteStringRJAttr(vw,"justified",4,10,REVERSE);
VirtualWriteStringRJAttr(vw,"on ",5,10,REVERSE);
VirtualWriteStringRJAttr(vw,"column",6,10,REVERSE);
VirtualWriteStringRJAttr(vw,"10",7,10,REVERSE);
WindowAssignToVirtual(w,vw,1,1);
}
The example above writes the text right justified on column
10 of the virtual window. If the virtual window is
NOATTRIBUTE, only the string is written.
The return values for VirtualWriteStringRJAttr() are the same
as VirtualWriteStringAttr().
Page 136 The C Window Library Page 136
Length Controlled Functions
---------------------------
VirtualWriteCharacters()
------------------------
The VirtualWriteCharacters() writes a specified number of
characters from a buffer to the virtual window. Here is the
prototype:
int VirtualWriteCharacters(VWPOINTER vw, char *buffer,
unsigned row, unsigned col,
unsigned length)
The first argument is the virtual window. The second
argument is the buffer where the characters are stored. The
third and fourth arguments are the (row,col) of where the
characters will be placed in the virtual window. The last
argument is the number of characters from buffer that will be
written.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
VWPOINTER vw;
char buf[] = "Hello World!!";
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteCharacters(vw,buf,1,1,11);
VirtualWriteCharacters(vw,buf,2,1,13);
WindowAssignToVirtual(w,vw,1,1);
}
The return values for VirtualWriteCharacters() are the same
as VirtualWriteString().
Page 137 The C Window Library Page 137
VirtualWriteAttributes()
------------------------
The VirtualWriteAttributes() writes a specified number of
attributes from a buffer to the virtual window. Here is the
prototype:
int VirtualWriteAttributes(VWPOINTER vw, char *buffer,
unsigned row, unsigned col,
unsigned length)
The first argument is the virtual window. The second
argument is the buffer where the attributes are stored. The
third and fourth arguments are the (row,col) of where the
attributes will be placed in the virtual window. The last
argument is the number of attributes from buffer that will be
written. If the window is NOATTRIBUTE, this function does
nothing.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
VWPOINTER vw;
char buf[13];
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
for (i=0;i<13;i++)
if (i % 2)
buf[i] = NORM;
else
buf[i] = REVERSE;
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteString(vw,"Hello World!!",1,1);
VirtualWriteAttributes(vw,buf,1,1,13);
WindowAssignToVirtual(w,vw,1,1);
}
The return values for VirtualWriteAttributes() are the same
as VirtualWriteStringAttr().
Page 138 The C Window Library Page 138
VirtualWriteCharAndAttr()
-------------------------
The VirtualWriteCharAndAttr() function writes a string of
character/attribute pairs to a virtual window. Use this
function if you have created a string of character/attribute
pairs, and want to output them easily. The string consists
of character and attributes in the following manner:
char-attr-char-attr...
Each character is followed by its corresponding video
attribute. Here is the prototype:
int VirtualWriteCharAndAttr(VWPOINTER vw, char *buffer,
unsigned row, unsigned col,
unsigned length)
The first argument is the virtual window. The second is the
buffer where the character and attributes are stored. The
third and fourth is the (row,col) position in the virtual
window to write, and the length argument is the number of
character/attribute pairs from the buffer to write. Please
note the difference in the meaning of the length argument in
this function as opposed to its use in the preceding
functions.
If the virtual window is NOATTRIBUTE, nothing is written to
the virtual window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
VWPOINTER vw;
char buf[26];
char *str = "Hello World!!";
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<26;i+=2,str++)
{
buf[i] = *str;
buf[i+1] = NORM;
}
VirtualWriteCharAndAttr(vw,buf,1,1,13);
Page 139 The C Window Library Page 139
WindowAssignToVirtual(w,vw,1,1);
}
The return values for VirtualWriteCharAndAttr() are the same
as VirtualWriteStringAttr().
VirtualWriteRepeatAttribute()
-----------------------------
The VirtualWriteRepeatAttribute() function writes an
attribute a specified number of times to a virtual window.
Here is a prototype:
int VirtualWriteRepeatAttribute(VWPOINTER vw, int attr,
unsigned row, unsigned col,
int count)
The attr argument is the attribute to use. The count
argument specifies the number of times to write the attribute
attr to the virtual window starting at (row,col). If the
virtual window is NOATTRIBUTE, this function returns an
error.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
VWPOINTER vw;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteString(vw,"Hello World!!",1,1);
VirtualWriteRepeatAttribute(vw,REVERSE,1,1,13);
WindowAssignToVirtual(w,vw,1,1);
}
The example above illustrates that the
VirtualWriteRepeatAttribute() writes the REVERSE attribute 13
times starting at row 1, column 1 of the virtual window w.
The return values for VirtualWriteRepeatAttribute() are the
same as VirtualWriteStringAttr().
Page 140 The C Window Library Page 140
VirtualWriteRepeatCharacter()
-----------------------------
The VirtualWriteRepeatCharacter() function writes a character
a specified number of times to a virtual window. Here is a
prototype:
int VirtualWriteRepeatCharacter(WPOINTER w, int ch, int row,
int col, int count)
The count argument is the character to use. The count
argument specifies the number of times to write the character
ch to the virtual window starting at (row,col).
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteRepeatCharacter(vw,'a',1,1,5);
VirtualWriteRepeatCharacter(vw,'b',2,1,5);
VirtualWriteRepeatCharacter(vw,'c',3,1,5);
WindowAssignToVirtual(w,vw,1,1);
}
The example above illustrates that the
VirtualWriteRepeatCharacter() writes the letter 'a', 'b', and
'c' 5 times on rows 1, 2, and 3 respectively.
The return values for VirtualWriteRepeatCharacter() are the
same as VirtualWriteString().
Page 141 The C Window Library Page 141
Formatted Write Functions
-------------------------
Format String
-------------
These functions write formatted output to virtual windows
just like the printf() function. There are two functions
that do this, namely VirtualPrintf() and VirtualPrintfAttr().
These functions use a format string that is similar to the
format string found in printf(). For example, %d, %s, %lf,
etc. and most of the escape sequences are supported. The
list of escape sequences supported are as follows:
\n - newline
\t - tab
\r - carriage return
\x - hexadecimal
Where Output is Placed
----------------------
The row and column of where the string will be written is
determined by the virtual window's logical cursor. The
logical cursor is advanced by both of these functions to one
column position after the last character is printed. If you
want to start at a particular row and column of the window,
you must move the cursor yourself by calling the
VirtualMoveCursor() function. This function is explained in
the MOVING THE LOGICAL CURSOR section.
When the virtual window is first initialized using
VirtualInitialize(), the logical cursor is automatically
moved to (1,1) of the virtual window.
VirtualSetWrap()
----------------
With these functions, any text that will exceed the
boundaries of the window will be wrapped to the next line.
If the output will exceed the last row of the window, the
window is automatically scrolled up by one line. This is the
default action to take when characters exceed the right edge
of the virtual window. If you want the output clipped
instead of wrapped, you must set the virtual window's wrap
flag using the VirtualSetWrap() function.
The VirtualSetWrap() function sets the virtual window's wrap
flag to either on or off. Here is the prototype:
int VirtualSetWrap(VWPOINTER vw, int option)
Page 142 The C Window Library Page 142
The second argument will be 0 if you want to turn the wrap
flag off, or 1 if you want to turn it on. If the wrap flag
is off, the output generated by
VirtualPrintf() and VirtualPrintfAttr() will be terminated
when the right edge of the window is reached. If the wrap
flag is on, the output is wrapped to the next line when the
right edge is reached. Unlike regular windows, the output is
not scrolled if the last line of the virtual window is
reached.
You can set the wrap flag to a virtual window at any time.
VirtualPrintf()
--------------
The VirtualPrintf() function writes formatted output to the
virtual window. Here is the prototype:
int VirtualPrintf(VWPOINTER vw, char *format [,arg1,...])
The first argument is the virtual window. The second
argument is a format string. The rest of the arguments are
optional arguments that are written to the virtual window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
VWPOINTER vw;
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
VirtualPrintf(vw,"3+2 is equal to %d\n",3+2);
GET_KEY();
VirtualPrintf(vw,"i is equal to %d\nj is equal to %lf\n",
i,j);
}
Page 143 The C Window Library Page 143
The above example illustrates how VirtualPrintf() is used to
print formatted strings to a virtual window.
The return values for VirtualPrintf() are the same as
VirtualWriteString().
VirtualPrintfAttr()
-------------------
The VirtualPrintfAttr() function writes formatted output to
the virtual window. The difference between VirtualPrintf()
and VirtualPrintfAttr() is that VirtualPrintfAttr() uses a
video attribute specified as an argument. Here is the
prototype:
int VirtualPrintfAttr(VWPOINTER vw, int attr,
char *format [,arg1,...])
The first argument is the virtual window. The second
argument is the video attribute to use. The third argument
is the format string. The rest of the arguments are optional
arguments that are written to the virtual window. If the
virtual window is NOATTRIBUTE, only the string is written to
the window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
VWPOINTER vw;
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
VirtualPrintfAttr(vw,REVERSE,"3+2 is equal to %d\n",3+2);
GET_KEY();
VirtualPrintfAttr(vw,REVERSE,
"i is equal to %d\nj is equal to %lf\n",i,j);
}
Page 144 The C Window Library Page 144
The above example illustrates how VirtualPrintfAttr() is used
to print formatted strings.
The return values for VirtualPrintfAttr() are the same as
VirtualWriteStringAttr().
Page 145 The C Window Library Page 145
READING CHARACTERS AND ATTRIBUTES FROM VIRTUAL WINDOWS
------------------------------------------------------
With The C Window Library, you can read the contents of a
virtual window into a character buffer. These functions
provide the programmer with the contents of the virtual
window at any time. The functions to perform this are
VirtualReadAttributes(), VirtualReadCharacters() and
VirtualReadCharAndAttr().
VirtualReadCharacters()
-----------------------
The VirtualReadCharacters() function reads the characters
from a virtual window into a buffer. Here is the prototype.
int VirtualReadCharacters(VWPOINTER vw, char *buffer,
unsigned row, unsigned col,
unsigned length)
The first argument is the virtual window. The second
argument is the buffer to store the characters in. The third
and fourth arguments are the (row,col) position in the
virtual window to start reading from. The last argument is
the number of characters to read.
You must make sure that buffer has enough room to hold all of
the characters read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
char buf[14] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,10,80,NORM);
VirtualWriteString(vw,"Hello World!!",1,1);
VirtualReadCharacters(vw,buf,1,1,13);
}
The example above illustrates the use of
VirtualReadCharacters(), which reads the virtual window's
contents starting at (1,1). This happens to be the string
"Hello World!!".
Page 146 The C Window Library Page 146
If the length exceeds the right edge of the virtual window,
VirtualReadCharacters() will read up to the right edge of the
virtual window.
If there are no errors, VirtualReadCharacters() returns
NO_ERROR.
If there are errors, VirtualReadCharacters() returns one of
the following:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the row or column specified in the virtual
window is out of bounds.
VirtualReadAttributes()
----------------------
The VirtualReadAttributes() function reads the attributes
from a virtual window into a buffer. Here is the prototype.
int VirtualReadAttributes(VWPOINTER w, char *buffer,
unsigned row, unsigned col,
unsigned length)
The first argument is the virtual window. The second
argument is the buffer to store the attributes in. The third
and fourth arguments are the (row,col) position in the
virtual window to start reading from. The last argument is
the number of attributes to read. If the virtual window is
NOATTRIBUTE, nothing is read.
You must make sure that buffer has enough room to hold all of
the attributes read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
char buf[14] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,10,80,NORM);
VirtualReadAttributes(vw,buf,1,1,13); /* Read attributes */
}
Page 147 The C Window Library Page 147
The example above illustrates the use of
VirtualReadAttributes(), which reads the virtual window's
attribute contents starting at (1,1) of the virtual window.
If the length exceeds the right edge of the virtual window,
VirtualReadAttributes() will read up to the right edge of the
virtual window.
If there are no errors, VirtualReadAttributes() returns
NO_ERROR.
If there are errors, VirtualReadAttributes() returns one of
the following:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the row or column specified in the virtual
window is out of bounds.
NO_ATTRIB if the virtual window is NOATTRIBUTE.
VirtualReadCharAndAttr()
------------------------
The VirtualReadCharAndAttr() function reads
character/attribute pairs from a virtual window into a
buffer. Here is the prototype.
int VirtualReadCharAndAttr(VWPOINTER w, char *buffer,
unsigned row, unsigned col,
unsigned length)
The first argument is the virtual window. The second
argument is the buffer to store the character/attribute pairs
in. The third and fourth arguments are the (row,col)
position in the virtual window to start reading from. The
last argument is the number of character/attribute pairs to
read. If the window is NOATTRIBUTE, nothing is read.
You must make sure that buffer has enough room to hold all of
the character/attribute pairs read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
char buf[27] = {0}; /* Null all elements of buf */
Page 148 The C Window Library Page 148
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,10,80,NORM);
VirtualWriteString(vw,"Hello World!!",1,1);
VirtualReadCharAndAttr(vw,buf,1,1,13);
}
The example above illustrates the use of
VirtualReadCharAndAttr(), which reads the virtual window's
character/attribute contents starting at (1,1) of the virtual
window. This happens to be the characters/attributes of the
string "Hello World!!".
If the length exceeds the right edge of the virtual window,
VirtualReadCharAndAttr() will read up to the right edge of
the virtual window.
If there are no errors, VirtualReadCharAndAttr() returns
NO_ERROR.
If there are errors, VirtualReadCharAndAttr() returns one of
the following:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the row or column specified in the virtual
window is out of bounds.
NO_ATTRIB if the virtual window is NOATTRIBUTE.
Page 149 The C Window Library Page 149
REPOSITIONING THE VIEWPORT
--------------------------
A viewport can be repositioned anywhere on the virtual
window. This allows to view different parts of the virtual
window.
WindowPositionViewport()
------------------------
The WindowPositionViewport() function positions the viewport
to a new location on the virtual window it is associated
with. Here is the prototype:
int WindowPositionViewport(WPOINTER w, unsigned row,
unsigned col)
The first argument is the viewport window. The second
argument and third arguments are is the (row,col) position of
the virtual window associated with w. This position will be
where the upper left hand corner of the viewport's text area
will be placed.
Example:
#include <stdio.h>
#include <string.h>
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define FILENAMECHARS \
"25[A-Za-z0-9!@#$%/^&()+=_/-{}/[/]`~/.\\:]"
VWPOINTER vw; /* virtual window pointer */
WPOINTER w; /* Window pointer */
char filename[26];
FILE *infile; /* input file handle */
main()
{
unsigned int i,j,row,col;
WindowInitializeSystem();
WindowSaveInitial(0);
/* set up a Type 0 virtual window */
vw = VirtualInitialize(NOATTRIBUTE,200,80,0);
/* set up viewport window */
w = WindowInitialize(BORDER,1,1,78,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
Page 150 The C Window Library Page 150
/* read a file name */
read_file();
/* display file in viewport */
WindowAssignToVirtual(w,vw,1,1);
row = col = 1;
flush_keyboard_flag = TRUE; /* Set keyboard flush to TRUE */
while (1)
{
switch (GET_KEY()) /* Keep getting keys until
ESCAPE key is hit */
{
case UARROW: /* Move viewport up 1 line */
if (row > 1)
WindowPositionViewport(w,--row,col);
break;
case DARROW: /* Move viewport down 1 line */
if (row < 189)
WindowPositionViewport(w,++row,col);
break;
case LARROW: /* Move viewport left 1 line */
if (col > 1)
WindowPositionViewport(w,row,--col);
break;
case RARROW: /* Move viewport right 1 line */
if (col < 69)
WindowPositionViewport(w,row,++col);
break;
case ESC: /* End program */
close_all();
break;
}
}
}
read_file() /* Gets a filename and displays
it in the window */
{
int ch;
unsigned r = 1, c = 1;
filename[0] = 0;
WindowWriteString(w,"Please enter a file name: ",1,1);
WindowGetString(w,1,27,filename,'_',0,40,0,FILENAMECHARS);
if ((infile = fopen(filename,"r")) == NULL)
{
WindowMoveCursor(w,3,1);
WindowPrintf(w,"File name %s does not exist\n"
"Press a key to continue", filename);
GET_KEY();
close_all();
}
else
Page 151 The C Window Library Page 151
while(1) /* Read characters into virtual window */
{
ch = fgetc(infile);
if (feof(infile))
break;
if (ch != '\n')
VirtualWriteRepeatCharacter(vw,ch,r,c++,1);
else
{
r++;
c=1;
}
}
fclose(infile);
}
close_all()
{
WindowClose(w,NOEFFECT);
exit(0);
}
The above example reads in a text file and uses
WindowPositionViewport() to move left, right, up, or down.
There is no checking to see if you have scrolled past the end
of the file.
The read_file() function reads a file and copies each
character in the file to the virtual window called vw.
In the main program, the global variable flush_keyboard_flag,
defined in the IMPORTANT GLOBAL VARIABLES section, is set to
TRUE. When flush_keyboard is TRUE, the keyboard buffer is
flushed before any incoming keystrokes are accepted.
Otherwise the keyboard buffer is not flushed.
In the while(1) loop of the main program, the constants
UARROW, DARROW, LARROW, and RARROW, stands for the up, down,
left, and the right arrow keys on the keypad, respectively.
The constants UARROW, DARROW, LARROW, and RARROW are defined
in keycodes.h. Depending on the key that is hit, the
viewport is repositioned to point to a new row or column.
The call to WindowPositionViewport() has three arguments.
The first is the pointer to the viewport window, the second
and the third are the row and the column of the virtual
window to place the upper left hand corner of the viewport.
There is minimal bounds checking in the above example,
however you can enhance it by putting in more bounds checking
and by implementing a page down, or page up function.
Page 152 The C Window Library Page 152
If there are no errors, WindowPositionViewport() returns
NO_ERROR. If there are errors, WindowPositionViewport() will
return one of the following values:
BAD_WINDOW if the viewport window does not exist.
BAD_V_WINDOW if the viewport is pointing to a virtual window
that does not exist.
V_WINDOW_BOUND if the row and col arguments are out of bounds
of the virtual window.
Page 153 The C Window Library Page 153
SCROLLING THE VIEWPORTS
-----------------------
Viewports can have its display scrolled left, right, up, or
down using the WindowScrollViewport() function described
below.
WindowScrollViewport()
---------------------
This functions scrolls the viewport specific number of
characters. Here is the prototype:
int WindowScrollViewport(WPOINTER w, unsigned num,
int direction)
The first argument is the viewport and the second argument is
the number of characters to scroll. The last argument is the
direction to scroll. This direction can be UP, DOWN, LEFT,
or RIGHT.
Example:
#include <stdio.h>
#include <string.h>
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define FILENAMECHARS \
"25[A-Za-z0-9!@#$%/^&()+=_/-{}/[/]`~/.\\:]"
VWPOINTER vw; /* virtual window pointer */
WPOINTER w; /* Window pointer */
char filename[26];
FILE *infile; /* input file handle */
main()
{
unsigned int i,j,row,col;
WindowInitializeSystem();
WindowSaveInitial(0);
/* set up a Type 0 virtual window */
vw = VirtualInitialize(NOATTRIBUTE,200,80,0);
/* set up viewport window */
w = WindowInitialize(BORDER,1,1,78,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
/* read a file name */
read_file();
Page 154 The C Window Library Page 154
/* display file in viewport */
WindowAssignToVirtual(w,vw,1,1);
flush_keyboard_flag = TRUE;
while (1)
{
switch (GET_KEY()) /* Keep getting keys until
ESCAPE key is hit */
{
case UARROW: /* Move viewport up 1 line */
WindowScrollViewport(w,1,UP);
break;
case DARROW: /* Move viewport down 1 line */
WindowScrollViewport(w,1,DOWN);
break;
case LARROW: /* Move viewport left 1 line */
WindowScrollViewport(w,1,LEFT);
break;
case RARROW: /* Move viewport right 1 line */
WindowScrollViewport(w,1,RIGHT);
break;
case ESC: /* End program */
close_all();
break;
}
}
}
read_file() /* Gets a filename and
displays it in the window */
{
int ch;
unsigned r = 1, c = 1;
filename[0]=0;
WindowWriteString(w,"Please enter a file name: ",1,1);
WindowGetString(w,1,27,filename,'_',0,40,0,FILENAMECHARS);
if ((infile = fopen(filename,"r")) == NULL)
{
WindowMoveCursor(w,3,1);
WindowPrintf(w,"File name %s does not exist\n"
"Press a key to continue", filename);
GET_KEY();
close_all();
}
else
while(1) /* Read characters into virtual window */
{
ch = fgetc(infile);
if (feof(infile))
break;
if (ch != '\n')
VirtualWriteRepeatCharacter(vw,ch,r,c++,1);
else
{
r++;
c=1;
Page 155 The C Window Library Page 155
}
}
fclose(infile);
}
close_all()
{
WindowClose(w,NOEFFECT);
exit(0);
}
The example above is the same as the example for the
WindowPositionViewport() function, except that the call to
WindowPositionViewport() is replaced with the appropriate
WindowScrollViewport() call.
For WindowScrollViewport(), the window is never scrolled if
the scroll will result in the upper left hand corner of the
viewport being out of bounds of the virtual window. For
example, you cannot scroll left 1 character if the viewport
is located at (1,1) of the virtual window, similarly you
cannot scroll right if the virtual window has a maximum of 80
characters and the upper left hand corner of the viewport is
situated at (1,80). The same restrictions apply for
scrolling up and down.
If there are no errors, all of the WindowScrollViewport()
functions will return NO_ERROR.
If there are errors, these functions will return the
following value:
V_WINDOW_BOUND if the scroll will cause the upper left hand
position of the viewport to be out of bounds.
Page 156 The C Window Library Page 156
WRITING VIRTUAL WINDOW CONTENTS TO A FILE
-----------------------------------------
The C Window Library allows you to print the contents of a
virtual window using the VirtualWriteTextToFile() function.
VirtualWriteTextToFile()
------------------------
The VirtualWriteTextToFile() function allows you to print the
contents of a virtual window to a file. Here is the
prototype:
int VirtualWriteTextToFile(VWPOINTER vw, char *filename,
int mode)
The first argument is the virtual window. The second
argument is the file name. This file can be any of the DOS
filenames ("con", "prn", "aux", etc.). The file specified by
filename must be closed before calling
VirtualWriteTextToFile(), and the file handle is
automatically closed before exiting VirtualWriteTextToFile().
The last argument is the mode switch. If mode is 1, a
newline ('\n') is written to the file after each line of the
virtual window written to the file. If mode is 0, no newline
character is written. When mode 0 is chosen, the file is
open in binary mode, else it is open in text mode.
Example:
#include "window.h"
VWPOINTER vw;
char *filename = "wintext";
char *filename2 = "wintext2";
main()
{
int i;
WindowInitializeSystem();
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
for (i=1;i<=10;i++)
VirtualWriteString(vw,"Hello World!!",i,1);
VirtualWriteTextToFile(vw,filename,1); /* use newlines */
VirtualWriteTextToFile(vw,filename2,0); /* no newlines */
}
The example above illustrates two calls to
VirtualWriteTextToFile(). The first call writes the contents
of the virtual window vw to a file called "wintext". Note
that the mode parameter for the first call is 1. This will
cause '\n' to be written to the file for each line of the
Page 157 The C Window Library Page 157
virtual window. The second call writes the virtual window
text to a file call "wintest2", with the mode parameter being
0 (no '\n').
Please note that VirtualWriteTextToFile() does not check if
the file already exists, so be careful that you do not
replace files that are important to you.
If there are no errors, VirtualWriteTextToFile() returns
NO_ERROR.
If there are errors, VirtualWriteTextToFile() will return one
of the following:
BAD_V_WINDOW if the virtual window does not exist.
FILE_CANT_OPEN if the file specified by filename cannot be
open.
FILE_CANT_CLOSE if the file specified by filename cannot be
closed.
Page 158 The C Window Library Page 158
MOVING THE LOGICAL CURSOR
-------------------------
You can move and get the position of the logical cursor in a
virtual window.
VirtualMoveCursor()
-------------------
The VirtualMoveCursor() function moves a virtual window's
logical cursor to a new location. Here is the prototype:
int VirtualMoveCursor(VWPOINTER vw, unsigned row,
unsigned col)
The first argument is the virtual window, and the second and
third arguments denote the new (row,col) position of the
logical cursor.
Example:
#include "window.h"
VWPOINTER vw;
main()
{
int i;
WindowInitializeSystem();
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
VirtualMoveCursor(vw,10,10) /* Moves the logical cursor
to row 10, column 10 of
the virtual window */
}
If there are no errors, VirtualMoveCursor() returns NO_ERROR.
If there are errors, VirtualMoveCursor() returns one of the
following values:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if either the row or column specified is out
of bounds.
VirtualGetCursorPosition()
--------------------------
The VirtualGetCursorPosition() function gives the current row
and column of the cursor in a virtual window. Here is the
prototype:
Page 159 The C Window Library Page 159
int VirtualGetCursorPosition(VWPOINTER vw, unsigned *row,
unsigned *col)
The row and col arguments are pointers to unsigned integers
that will contain the row and column of the cursor after
VirtualGetCursorPosition() is called.
Example:
#include "window.h"
VWPOINTER vw;
main()
{
unsigned row,col;
WindowInitializeSystem();
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
VirtualMoveCursor(vw,7,4);
VirtualGetCursorPosition(vw,&row,&col);
}
If there are no errors, VirtualGetCursorPosition() returns
NO_ERROR.
If there are errors, VirtualGetCursorPosition() returns the
following value:
BAD_V_WINDOW if the window does not exist.
Page 160 The C Window Library Page 160
CLEARING VIRTUAL WINDOWS
------------------------
The C Window Library contains functions that clears the
entire virtual window, or clears defined rectangular regions
of the virtual window.
VirtualClear()
--------------
The VirtualClear() function clears an entire virtual window
to spaces. Here is the prototype:
int VirtualClear(VWPOINTER vw)
The only argument is the virtual window to clear.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
for (i=1;i<=10;i++)
VirtualWriteString(vw,"Hello World!!",i,1);
GET_KEY();
VirtualClear(vw);
}
If there is no error, VirtualClear() returns NO_ERROR.
If there is an error, VirtualClear() returns the following
values:
BAD_V_WINDOW if the virtual window does not exist.
Page 161 The C Window Library Page 161
VirtualClearAttr()
------------------
The VirtualClearAttr() function works the same way as the
VirtualClear() function except that an attribute is
specified. Here is the prototype:
int VirtualClearAttr(VWPOINTER vw, int attr)
The second argument is the video attribute to use. If the
virtual window is NOATTRIBUTE, this function only clears the
text.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
VWPOINTER vw;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
for (i=1;i<=10;i++)
VirtualWriteString(vw,"Hello World!!",i,1);
GET_KEY();
VirtualClearAttr(vw,REVERSE);
}
The return values for VirtualClearAttr() are the same as
VirtualClear(), except for the following error:
NO_ATTRIB if the virtual window is NOATTRIBUTE.
VirtualClearRegion()
-------------------
The VirtualClearRegion() function clears a region of a
virtual window. To use the VirtualClearRegion() function,
you must describe the rectangular region to clear. Here is
the prototype:
int VirtualClearRegion(VWPOINTER vw, unsigned urow,
unsigned ucol, unsigned lrow,
unsigned lcol)
Page 162 The C Window Library Page 162
where (urow,ucol) describes the upper left of the rectangle
and (lrow,lcol) is the lower right of the virtual window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
VWPOINTER vw;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
for (i=1;i<=10;i++)
VirtualWriteString(vw,"Hello World!!",i,1);
GET_KEY();
VirtualClearRegion(vw,4,4,8,15);
}
The VirtualClearRegion() call will clear the region described
by the rectangular coordinates (4,4) and (8,15).
If there is no error, VirtualClearRegion() returns NO_ERROR.
If there is an error, the VirtualClearRegion() function will
return the following values:
BAD_V_WINDOW if the VWPOINTER vw does not exist.
V_WINDOW_BOUND if the rectangular region defined is out of
bounds of the virtual window.
VirtualClearRegionAttr()
------------------------
The VirtualClearRegionAttr() function works the same as the
VirtualClearRegion() function, except that a video attribute
is specified. Here is the prototype:
int VirtualClearRegionAttr(VWPOINTER vw, unsigned urow,
unsigned ucol, unsigned lrow,
unsigned lcol, int attr)
Page 163 The C Window Library Page 163
The attr argument is a video attribute to use to clear the
region. If the virtual window is NOATTRIBUTE, the attribute
argument is ignored.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
VWPOINTER vw;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
for (i=1;i<=10;i++)
VirtualWriteString(vw,"Hello World!!",i,1);
GET_KEY();
VirtualClearRegionAttr(vw,4,4,8,15,REVERSE);
}
The VirtualClearRegionAttr() call will clear the region
described by the rectangular coordinates (4,4) and (8,15)
using the video attribute defined by the constant REVERSE.
The VirtualClearRegionAttr() returns the same values as
VirtualClearRegion() with an additional error condition:
NO_ATTRIB if the virtual window is NOATTRIBUTE.
Page 164 The C Window Library Page 164
FREEZING VIEWPORTS
------------------
You can temporarily suspend or 'freeze' a viewport window
from displaying updates to the virtual window. This is good
if there is data being written to the virtual window which
takes a long time to generate. The viewport can be frozen
when the information is being written, and unfrozen when the
writing of the data is terminated.
WindowFreeze()
--------------
The WindowFreeze() function suspends or resumes displaying of
virtual window updates on a viewport window. Here is the
prototype:
int WindowFreeze(WPOINTER w, int option)
The first argument is the viewport window, and the second
argument is the option flag. If this flag is 0, the window
is unfrozen, i.e. the window will display virtual window
updates. If it is 1, the window will suspend virtual window
updates from being displayed.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,10,80,NORM);
WindowOpen(w);
WindowAssignToVirtual(w,vw,1,1);
WindowDisplay(w,1,NOEFFECT);
/* Freeze Viewport */
WindowFreeze(w,1);
for (i=1;i<=10;i++)
{
delay(1000);
VirtualPrintf(vw,"Line %d\n",i);
}
/* Unfreeze window */
WindowFreeze(w,0);
Page 165 The C Window Library Page 165
GET_KEY();
/* Now try with window always displaying data */
VirtualClear(vw);
for (i=1;i<=10;i++)
{
delay(1000);
VirtualPrintf(vw,"Line %d\n",i);
}
}
The above program first freezes the viewport w with the first
call to WindowFreeze(). Then text is written slowly to the
virtual window vw. This text is not displayed until the
window is unfrozen again with the second call to
WindowFreeze(). Everything is reset and the writing of the
text to the virtual window is done again, but this time the
viewport is always displaying virtual window updates, even
when the text is being written to the virtual window.
The delay() function is discussed in the TIMED DELAYS
section.
If there is no error WindowFreeze() returns NO_ERROR.
If there are errors, WindowFreeze() returns one of the
following values:
BAD_WINDOW if the viewport window does not exist.
BAD_V_WINDOW if the virtual window that the viewport is
displaying does not exist.
Page 166 The C Window Library Page 166
DISPOSING OF VIRTUAL WINDOWS
----------------------------
The last step is to dispose of the virtual window. The
function to do this is the VirtualFree() function.
VirtualFree()
-------------
The VirtualFree() function frees all the memory allocated to
the virtual window and destroys the virtual window pointer.
Here is the prototype:
int VirtualFree(VWPOINTER vw, int hideflag, int effect)
The first argument is the virtual window. The second
argument is a flag that determines whether any viewports
displaying the virtual window should be hidden. If this
argument is 1, all viewports displaying the virtual window is
hidden. If the argument is 0, all viewports are cleared, but
not hidden. The third argument is the special effect to use
when hiding the viewports. This argument is ignored if
hideflag is 0. For a list of special effects, refer to the
DISPLAYING WINDOWS section.
Once VirtualFree() is called you must not use the VWPOINTER
again unless you assign it to another virtual window, or
create a new virtual window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointer */
WPOINTER w1, w2;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
w1 = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,
SINGLEBOX);
w2 = WindowInitialize(BORDER,13,1,20,10,NORM,NORM,
DOUBLEBOX);
WindowOpen(w1);
WindowOpen(w2);
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
VirtualWriteString(vw,"This is a string",1,1);
WindowAssignToVirtual(w1,vw,1,1);
WindowAssignToVirtual(w2,vw,1,1);
Page 167 The C Window Library Page 167
GET_KEY();
VirtualFree(vw,1,NOEFFECT);
}
If there are no errors, VirtualFree() returns NO_ERROR.
If there are errors, VirtualFree() returns the following
value:
BAD_V_WINDOW if the virtual window does not exist.
Page 168 The C Window Library Page 168
INTRODUCTION TO MENU SYSTEM
---------------------------
Menu systems are important entities in any program. The C
Window Library has functions that create popup, pull-down,
and bar menus. The popup menus are scrollable menus with a
limit of 65,535 selections. The bar menus can have any
number of entries. As of this version, the bar menus are not
scrollable, although there will be an implementation of
scrolling bar menus in a future version. The pull-down menus
are a combination of popup and bar menus. You can change
entries, hide entries, use hotkeys to invoke a menu entry,
and many more things.
Menu Manager
------------
The menu manager is the code in The C Window Library that
handles moving the highlight bar in the menu, calling the
menu functions when they are selected, keeps tracks of
available entries, and other functions that keep track of the
menu when selections are made.
Necessary "include" files
-------------------------
To use the menu system in your program, you must include the
"menu.h" file supplied. This file automatically includes the
"window.h" file, therefore you do not have to include
"window.h" when you use "menu.h".
Page 169 The C Window Library Page 169
POP-UP MENUS
------------
Description
-----------
A popup menu is a vertical menu with a list of entries that
are selected by placing a highlight bar on the entry and
pressing return, or by invoking the function by using a
hotkey. Pop-up menus can be scrollable, in other words, if
there are more entries than can be displayed in the window,
the menu will scroll through the rest of the selections. You
can have up to 65,535 selections in the popup menu.
Here is a partial list of the various options you can have
with popup menus:
* Highlight bar wrapping - wrap highlight bar to first or
last option when there are no
more selections.
* Static Menus - menu remains on the screen when entry is
selected.
* Perpetual Menus - menu remain on the screen regardless
of whether the PopupSelectMenu() function (explained
later) is called or not.
* Hidden (Unavailable) entries - You can make an entry in
the popup menu
unavailable or available
at any time.
* Color scheme of the menu - You can customize the color
of the highlight bar, the
hotkey letters, hidden
entries, etc.
* Change entry names - You can safely change the names
displayed in the menu at any
time.
* Use a mouse to select menu entries.
Windows and Virtual Windows
---------------------------
Pop-up menus use virtual windows to write menu selections,
and use normal windows to display the selections. This
method of using virtual windows enables the menu manager to
scroll through the menu selections if the window is not tall
enough to display all of the selections.
Page 170 The C Window Library Page 170
CREATING POP-UP MENUS
---------------------
The POPUP_MENU_ENTRY structure
------------------------------
The two most important parts of the popup menu are the
POPUP_MENU_ENTRY structure and the POPUP_MENU_PTR structure.
The POPUP_MENU_ENTRY structure is the first step in creating
a popup menu and is discussed here.
Each entry in the popup menu has its own POPUP_MENU_ENTRY
structure associated with it. The layout of this structure
is as follows:
char *entry_name -- This is the string that is
displayed in the popup virtual
window.
unsigned row -- Row in the virtual window to
display entry_name.
char hotkey_letter -- This is a character in entry_name
that is highlighted from the rest
of the characters in entry_name.
This letter will automatically
invoke the menu function
associated with entry_name.
unsigned ext_hotkey -- This is a secondary hotkey. The
difference between hotkey_letter
and ext_hotkey is that ext_hotkey
can handle keys that are not
ASCII keys (the F keys, Alt and
Ctrl key combinations, etc.).
int (*func)() -- Pointer to function that is
invoked when option is selected.
An array of POPUP_MENU_ENTRY's are needed to create all of
the entries on the popup menu. The order of the array
elements determine the order of how they are placed in the
virtual window. A code sample to create an array of
POPUP_MENU_ENTRY's would be as follows:
#include "menu.h"
int menu_func();
POPUP_MENU_ENTRY menu_items[] = {
" Load F3", /* entry name */
1, /* row number */
'L', /* hotkey */
Page 171 The C Window Library Page 171
F3, /* secondary hotkey */
menu_func, /* function to call if
chosen */
/* now do rest of the popup entries */
" Pick Alt-F3",2, 'P',ALTF3,menu_func,
" New" ,3, 'N',0,menu_func,
" Save F2",4, 'S',F2,menu_func,
" Write to ",5, 'W',0,menu_func,
" Directory ",6, 'D',0,menu_func,
" Change Dir" ,7, 'C',0,menu_func,
" OS shell" ,8, 'O',0,menu_func,
" Quit Alt-X" ,9,'Q',ALTX,menu_func,
/* Terminate with a CWL_NULL and 0 */
CWL_NULL,0};
The first include file, menu.h, is must be included in each
source file that calls menu functions.
As you can see, there is an array of POPUP_MENU_ENTRY's,
namely menu_items. Each entry consists of an entry name, row
number, hotkey letter, secondary hotkey, and a function to
call when the entry is selected. The list of
POPUP_MENU_ENTRY's MUST be terminated by a CWL_NULL entry
name, and a row number of 0. If this rule is violated, the
menu manager will not know where the last entry is, and will
cause chaos when the program is run.
There is an alternate method of creating the array of
POPUP_MENU_ENTRY's. Later on we will discuss creating these
entries dynamically.
Defining Hotkeys
----------------
The hotkey_letter defined in the POPUP_MENU_ENTRY structure
must match one of the letters in its corresponding
entry_name. For example, " Load F3", has the
hotkey_letter defined as 'L'. Since 'L' matches the first
letter in " Load F3", the first 'L' in " Load F3" is
highlighted. If there is no match, or if the hotkey_letter
is 0, there is no hotkey associated with this option. When
the menu is displayed, either the 'l' or 'L' will be accepted
as a valid selection to the entry " Load F3". If there
is a POPUP_MENU_ENTRY with the same hotkey letter as another
POPUP_MENU_ENTRY, the POPUP_MENU_ENTRY closest to the first
entry is chosen.
Page 172 The C Window Library Page 172
The ext_hotkey is used if the hotkey cannot be defined as a
single character, or if you want another hotkey definition.
In the above example, the " Load F3" entry_name has an
ext_hotkey of F3 (defined in keycodes.h). If the F3 key is
pressed, the function menu_func() is automatically invoked.
If the ext_hotkey letter is 0, there is no ext_hotkey
defined. If there is a POPUP_MENU_ENTRY with the same
ext_hotkey as another POPUP_MENU_ENTRY, the POPUP_MENU_ENTRY
closest to the first entry is chosen.
Assigning the function to perform
---------------------------------
The func() member is the function that is performed when its
corresponding entry_name is chosen.
This is the first step in completing the total popup menu.
Once the array of POPUP_MENU_ENTRY's is created the next step
is to define the colors for each element of the popup menu.
Coloring Popup Menus
--------------------
An array of unsigned integers is used to define the color
scheme of the popup menu. Each element of this array stands
for a certain area of the popup menu. Here is a list of
array positions and what they stand for.
Position
Constant
--------
ENTRYCOLOR -- color of the text area of the viewport
window.
BORDERCOLOR -- color of the border of the viewport window.
HOTKEYCOLOR -- color of the hotkey letter.
HIGHLIGHTCOLOR -- color of the highlight bar.
UNAVAILCOLOR -- color of the unavailable entries.
Position ENTRYCOLOR of the array defines the color of the
text area of the viewport window. This in turn defines the
color of each entry_name of all of the POPUP_MENU_ENTRY's.
Position BORDERCOLOR defines the color of the border of the
viewport window. As was stated above, the menu is written to
a virtual window, and a viewport is used to display the menu
Page 173 The C Window Library Page 173
entries. If the viewport window does not have a border, this
attribute is ignored.
Position HOTKEYCOLOR defines the color to use for the hotkey
letter. In the above example, the 'L', 'P', 'N', etc. of
each respective entry_name is displayed using this color.
Position HIGHLIGHTCOLOR defines the color used for the
highlight bar. This bar is moved up and down when the user
is making a selection.
Position UNAVAILCOLOR defines the color of the unavailable
menu entries. Whenever a menu entry is unavailable, the
entry_name string displayed takes on this color.
Colors can be created by using the CREATE_VIDEO_ATTRIBUTE().
A code sample to create the colors is as follows:
#include "menu.h"
unsigned int menu_colors[5];
main()
{
{... code ...}
menu_colors[ENTRYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[BORDERCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[HOTKEYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(blue,white);
menu_colors[HIGHLIGHTCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,cyan);
menu_colors[UNAVAILCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
/* rest of the program */
}
Creating popup menu entries dynamically
---------------------------------------
You can create POPUP_MENU_ENTRY's dynamically, instead of
defining a pre-determined array of POPUP_MENU_ENTRY's
explained previously. Here is an example:
Usual method:
------------
POPUP_MENU_ENTRY menu_items[] = {
" Load F3", /* entry name */
1, /* row number */
'L', /* hotkey */
Page 174 The C Window Library Page 174
F3, /* secondary hotkey */
menu_func, /* function to call if
chosen */
" Pick Alt-F3",2, 'P',ALTF3,menu_func,
" New" ,3, 'N',0,menu_func,
" Save F2",4, 'S',F2,menu_func,
" Write to ",5, 'W',0,menu_func,
" Directory ",6, 'D',0,menu_func,
" Change Dir" ,7, 'C',0,menu_func,
" OS shell" ,8, 'O',0,menu_func,
" Quit Alt-X" ,9,'Q',ALTX,menu_func,
/* Terminate with a CWL_NULL and 0 */
CWL_NULL,0};
Dynamic Method
--------------
#include "menu.h"
#define NUMENTRIES 9
POPUP_MENU_ENTRY_PTR menu_array; /* Notice that we have a
pointer to what
will be an array of
POPUP_MENU_ENTRY's
*/
POPUP_MENU_PTR p;
main()
{
WindowInitializeSystem();
/* Initialize with at least number of total entries */
menu_array = PopupAllocate(NUMENTRIES);
/* Call function to create entries in
menu_array sequentially */
PopupCreateEntry(menu_array, /* POPUP_MENU_ENTRY pointer */
1, /* entry number */
/* The rest of the arguments are just like the old method */
" Load F3", /* menu string */
1, /* row number */
'L', /* hotkey letter */
F3, /* secondary hotkey */
menu_func); /* function to perform */
/* do rest of the entries */
PopupCreateEntry(menu_array,2," Pick Alt-F3",2,'P',ALTF3,
menu_func);
Page 175 The C Window Library Page 175
PopupCreateEntry(menu_array,3," New",3,'N',0,menu_func);
PopupCreateEntry(menu_array,4," Save F2",4,'S',F2,
menu_func);
PopupCreateEntry(menu_array,5," Write to ",5,'W',0,
menu_func);
PopupCreateEntry(menu_array,6," Directory ",6,'D',0,
menu_func);
PopupCreateEntry(menu_array,7," Change Dir ",7,'C',0,
menu_func);
PopupCreateEntry(menu_array,8," OS Shell ",8,'O',0,
menu_func);
PopupCreateEntry(menu_array,9," Quit Alt-X ",9,'Q',ALTX,0,
menu_func);
/* end all of the menu entries */
PopupEntryEnd(menu_array,NUMENTRIES);
/* create menu */
p = PopupCreateMenu(menu_array, ... /* other arguments */);
/* ... */
/* Dispose of menu entries created */
PopupDeallocate(menu_array);
}
The difference between the above method and the method used
to globally initialize an array are the following:
1) The variable type for menu_array is POPUP_MENU_ENTRY_PTR,
not POPUP_MENU_ENTRY as the normal method would have done.
2) You must call the PopupAllocate() function to allocate
space for the number of entries desired. If you do not
call PopupAllocate(), you will surely get a memory
overwrite error. The return value to PopupAllocate() must
be assigned to a POPUP_MENU_ENTRY_PTR, as the above
example shows.
The array of menu entries are allocated from the heap at
runtime, as opposed to the static method which sets up the
memory scheme at link time.
3) The next thing you must do is to fill in the entry
information by calling the PopupCreateEntry() function.
The first argument to the PopupCreateEntry() function is
the POPUP_MENU_ENTRY_PTR. The second argument is the
entry number to assign this information to. The rest of
Page 176 The C Window Library Page 176
the arguments are the same order as the usual method i.e.
menu string, row, hotkey, etc. PopupCreateEntry() is
called for each field desired.
4) The PopupEndEntry() function must be called to terminate
the list of entries. The first argument is the
POPUP_MENU_ENTRY_PTR, and the second argument is the total
number of entries defined.
5) You should call PopupDeallocate() to free the memory
assigned to the array of menu_entries. The only argument
to PopupDeallocate() is the POPUP_MENU_ENTRY_PTR. Only
call PopupDeallocate() after you have called
PopupMenuFree() or any function that disposes of the
POPUP_MENU_PTR.
All of these functions except for PopupAllocate() have no
return values. The PopupAllocate() function returns a
POPUP_MENU_ENTRY_PTR if successful, and a null pointer if
unsuccessful.
The advantages of using the above method over the first
method is that POPUP_MENU_ENTRY's are dynamically allocated
rather than statically declared at compile time. This allows
the programmer to create loops to set up the entries, read
entry information from a file and assign this info to a
POPUP_MENU_ENTRY, etc.
You could also do the following:
#include "menu.h"
#define NUMENTRIES 9
POPUP_MENU_ENTRY menu_array[NUMENTRIES+1]; /* We must have at
least 1 more than the
number of entries */
POPUP_MENU_PTR p;
main()
{
/* ... */
/* Call function to create entries
in menu_array sequentially */
PopupCreateEntry(menu_array,1," Load F3",1,'L',F3,
menu_func);
PopupCreateEntry(menu_array,2," Pick Alt-F3",2,'P',ALTF3,
menu_func);
PopupCreateEntry(menu_array,3," New",3,'N',0,menu_func);
Page 177 The C Window Library Page 177
PopupCreateEntry(menu_array,4," Save F2",4,'S',F2,
menu_func);
PopupCreateEntry(menu_array,5," Write to ",5,'W',0,
menu_func);
PopupCreateEntry(menu_array,6," Directory ",6,'D',0,
menu_func);
PopupCreateEntry(menu_array,7," Change Dir ",7,'C',0,
menu_func);
PopupCreateEntry(menu_array,8," OS Shell ",8,'O',0,
menu_func);
PopupCreateEntry(menu_array,9," Quit Alt-X ",9,'Q',ALTX,0,
menu_func);
/* end all of the menu entries */
PopupEntryEnd(menu_array,NUMENTRIES);
}
The method above does not call PopupAllocate() because the
number of entries was already determined and an array was
already set up at compile time.
PopupCreateEntry() is called for each menu entry as before,
and PopupEntryEnd() is called to terminate the menu entries.
To use this method, you must declare an array of menu entries
with at least one more than the desired number of entries.
Also note that PopupDeallocate() MUST NOT be called because
the array of menu entries was not created with
PopupAllocate().
Page 178 The C Window Library Page 178
PopupCreateMenu() function
--------------------------
Now that you have created the POPUP_MENU_ENTRY's, and defined
the color scheme, it is time to wrap all of these loose ends
in one package. The next step is to call the
PopupCreateMenu() function. This function combines all of
the POPUP_MENU_ENTRY's, the colors you have defined, and
other information into one entity called a POPUP_MENU_PTR.
A POPUP_MENU_PTR is a pointer to a popup menu structure.
Just like a WPOINTER is a pointer to a window, a
POPUP_MENU_PTR is used to reference the popup menu.
A prototype of the call to PopupCreateMenu() is as follows:
POPUP_MENU_PTR PopupCreateMenu(POPUP_MENU_ENTRY *p,
unsigned *color, int row,
int col, int height,
unsigned options,
WPOINTER (*wfunc)(),
VWPOINTER (*vfunc)())
To illustrate how to use this call, let's use the
POPUP_MENU_ENTRY's and colors created in the previous
examples:
#include "menu.h"
int menu_func();
POPUP_MENU_ENTRY menu_items[] = {
" Load F3", 1,'L',F3,menu_func,
" Pick Alt-F3",2, 'P',ALTF3,menu_func,
" New" ,3, 'N',0,menu_func,
" Save F2",4, 'S',F2,menu_func,
" Write to ",5, 'W',0,menu_func,
" Directory ",6, 'D',0,menu_func,
" Change Dir" ,7, 'C',0,menu_func,
" OS shell" ,8, 'O',0,menu_func,
" Quit Alt-X" ,9,'Q',ALTX,menu_func,
CWL_NULL,0};
unsigned int menu_colors[5];
POPUP_MENU_PTR p;
main()
{
WindowInitializeSystem();
/* define colors */
menu_colors[ENTRYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[BORDERCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[HOTKEYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(blue,white);
menu_colors[HIGHLIGHTCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,cyan);
Page 179 The C Window Library Page 179
menu_colors[UNAVAILCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a POPUP_MENU_PTR */
WindowSaveInitial(0); /* Save initial screen */
p = PopupCreateMenu(menu_items,menu_colors,
10,10,9,NO_POPUP_OPTIONS,
WNULLFN,VWNULLFN);
/* rest of the code */
}
In the example above there are two function calls that must
be done before calling PopupCreateMenu(). The first
mandatory function is WindowInitializeSystem(). The other
function must be WindowSaveInitial() The
WindowInitializeSystem() function must be called to
initialize global variables used by the menu manager. The
WindowSaveInitial() function is a mandatory function because
the PopupCreateMenu() function creates windows and virtual
windows and assumes that the base screen has been saved.
The example above declares the variable p to be a
POPUP_MENU_PTR. This POPUP_MENU_PTR is going to be used to
reference the popup menu throughout the program.
The first argument to PopupCreateMenu() is a pointer to the
first POPUP_MENU_ENTRY. In the above example, menu_items is
a pointer to the first POPUP_MENU_ENTRY.
The second argument is a pointer to the array of colors. In
our example, menu_colors is our array of colors.
The third and fourth arguments denote the row and column to
place the upper left hand corner of the popup menu window.
The fifth argument is the height of the popup menu window.
If the height of the window will not accommodate all of the
menu items, the menu manager will scroll the window so that
the entries that are obscured come into view.
The sixth argument are various popup menu options that are
assigned to the popup menus which are defined below.
Popup Menu Options
------------------
By default the menu manager assumes the following things:
1) The highlight bar does not wrap if the user wants to move
the bar past the last entry, or before the first entry.
Page 180 The C Window Library Page 180
2) The menu will be hidden from the screen when a selection
is made and will reappear when control is returned to
the menu manager.
3) A function is automatically invoked when the hotkey is
pressed instead of calling a user-defined function
which will tell the menu manager whether the menu entry
is to be executed.
4) The popup menu window is hidden when the menu manager
returns control to the calling function.
5) The highlight bar will skip unavailable entries.
6) The menu manager does not recognize enhanced keys (F11,
F12, etc.).
7) The mouse will not be used to move the highlight bar.
8) Scroll characters will not be displayed on the popup
window. The scroll characters allow the user to scroll
through the options with a mouse.
The last two options are only available if you have a
Microsoft compatible mouse, and the mouse is activated.
If the constant NO_POPUP_OPTIONS is used, the assumptions
above are used. If you want to override the above defaults,
use the following options:
Option Name Definition
----------- ----------
POPUPWRAP Highlight bar wrapping.
POPUPSTATIC Do not hide menu when selection is
made.
POPUPCONFIRM Confirmation when selection is made
via hotkey.
POPUPDISPLAY Display menu even after exit.
POPUPOVERRIDE Accept Unavailable entries.
POPUPENHANCEDKEY Recognize enhanced keys.
POPUPMOUSE Use the mouse to select entries.
POPUPMOUSESCROLL Use the mouse to scroll through
entries by placing mouse on
hotspots.
As was stated before, the last two options, POPUPMOUSE and
Page 181 The C Window Library Page 181
POPUPSCROLLCHARS, can only be used if you have a mouse
installed, and the mouse is activated. More information on
these two options is given in the USING A MOUSE section.
By turning the above options "on" the following is assumed:
1) POPUPWRAP will wrap the highlight bar if the user wants
to move the bar past the last entry or before the first
entry.
2) POPUPSTATIC will not hide the menu when a selection is
made.
3) POPUPCONFIRM will call a user-defined function before
invoking the hotkey that was selected. This function
will then return an integer back to the menu manager
informing whether the function selected should be
invoked, or the request should be rejected. There is
more information on this option in the SETTING OPTIONS
IN POPUP MENUS section below.
4) POPUPDISPLAY will not hide the popup window when the menu
manager returns control to the calling function.
5) POPUPOVERRIDE will make the menu manager accept
unavailable entries.
6) POPUPENHANCEDKEY will inform the menu manager that
enhanced keys will be recognized.
7) POPUPMOUSE allows the use of a mouse to make selections.
8) POPUPMOUSESCROLL allows the user to scroll through the
options using a mouse.
You can also set multiple options by using a bitwise OR (|).
For example:
p = PopupCreateMenu(arg1,arg2,arg3,arg4,arg5,
POPUPWRAP | POPUPSTATIC | POPUPCONFIRM,arg7,arg8)
will set options POPUPWRAP, POPUPSTATIC, and POPUPCONFIRM
defined above.
The last two arguments to PopupCreateMenu() are defined in
the next sections.
Default Popup Window and Creating Your own Windows
--------------------------------------------------
The sixth argument to the PopupCreateMenu() function is a
pointer to a function that will open a popup menu window. If
this is a NULL function pointer (WNULLFN), the menu manager
Page 182 The C Window Library Page 182
will create a window. For most applications, the window that
the menu manager will create is adequate. The menu manager
uses these defaults when making the popup window:
- A bordered window with the border consisting of single
lines (SINGLEBOX).
- The width of the window is determined by the longest
entry_name in the POPUP_MENU_ENTRY's.
If you want to create your own popup menu window, your
function must return a WPOINTER. Inside your function you
must create and open a window using WindowInitialize() and
WindowOpen(). For most applications, you do not have to
display the window, instead the menu manager can do the
displaying and hiding of the windows.
Here is an example of creating your own custom window
function:
#include "menu.h"
/* Other includes and menu stuff */
WPOINTER my_open();
POPUP_MENU_PTR p;
main()
{
/* Other code */
p =
PopupCreateMenu(menu_items,menu_colors,10,10,9,
my_open,WNULLFN);
/* More code */
}
WPOINTER my_open()
{
WPOINTER w;
w = WindowInitialize(NOBORDER,1,1,20,10,BLACKONWHITE,
BLACKONWHITE,"");
WindowOpen(w);
return w; /* May be WIN_NULL_PTR, but must return to
PopupCreateMenu() */
}
The example above lets the menu manager know that the window
creation function is a user written function called my_open.
The row, column and height arguments (arguments 3, 4 and 5)
of PopupCreateMenu() will be ignored when using a custom
window function. The row, column and height parameters used
to create the window in the call to WindowInitialize() in
my_window() will take precedence over the arguments 3, 4, and
5 used in PopupCreateMenu().
Page 183 The C Window Library Page 183
Default Virtual Window and
Creating Your own Virtual Windows
---------------------------------
The last argument to PopupCreateMenu() is a pointer to a
function that will return a VWPOINTER. This function creates
the virtual window used to write the menu entries. If this
is a NULL function pointer (VWNULLFN), the menu manager will
create the virtual window. If you do specify a function,
your virtual window must have enough rows to hold all of the
POPUP_MENU_ENTRY's, and be wide enough to hold the length of
the longest entry_name.
When the menu manager creates the virtual window, the
following defaults are assumed:
a) the virtual window has its own video attributes.
b) Must be large enough to hold all the POPUP_MENU_ENTRY's.
Your custom function should create a virtual window which
follows both rules.
You must also make sure that the virtual window was created
and opened successfully. If the virtual window cannot be
created because of a lack of memory, you must return the NULL
virtual window pointer instead. From there,
PopupCreateMenu() will do any cleaning up and will return
with a null POPUP_MENU_PTR.
My last advice when calling the PopupCreateMenu() function is
that your best bet is to let the menu manager create the
windows and virtual windows. You can always resize, change
border types, etc. later on. Since virtual window's are not
visible anyway, it makes sense to let the menu manager
determine how the virtual window should be created. The last
two arguments to the PopupCreateMenu() function are for those
programmers who need full control of window, and virtual
window management.
Accessing Popup Windows and Virtual Windows
-------------------------------------------
After calling the PopupCreateMenu() function, you can access
the popup window by using the POPUP_WINDOW() macro. In the
above example, p is the POPUP_MENU_PTR and the value of
POPUP_WINDOW(p) is a pointer to the popup menu's window. If
you want to change borders move, slide, or anything you can
do with normal windows, you must access the popup window in
this way.
For example, if you want to change the border of the popup
window you would do the following:
Page 184 The C Window Library Page 184
p = PopupCreateMenu(... /* other arguments */ )
WindowDrawBorder(POPUP_WINDOW(p),DOUBLEBOX);
The example calls WindowDrawBorder() to change the border of
the popup window.
If you want to write information to the virtual window
created by the PopupCreateMenu() function, you can access the
virtual window by using the POPUP_VIRTUAL_WINDOW() macro. By
accessing the popup-menu's virtual window, you can read and
write to and from the virtual window. This is very useful if
you want to draw horizontal lines in your menu. An example
would be as follows:
char *h = "----------------------";
/* ...Some code... */
p = PopupCreateMenu(menu_items,menu_colors,10,10,9,
WNULLFN,VWNULLFN);
VirtualWriteString(POPUP_VIRTUAL_WINDOW(p),h,8,1);
Warnings
--------
Do not call WindowFree(), WindowClose() or VirtualFree() on
the window or the virtual window of the popup menu. The menu
manager will call these functions when PopupMenuFree() is
called. If you close the popup window, or the virtual window
on an active menu, the menu manager will assume that these
windows still exist. Doing so will almost guarantee your
application will bomb out.
Return Values for PopupCreateMenu()
-----------------------------------
If there are no errors, PopupCreateMenu() returns a valid
POPUP_MENU_PTR pointer. If there is an error when
PopupCreateMenu() is called, a null POPUP_MENU_PTR is
returned. Here are the possible reasons why an error has
occurred:
1) There is not enough memory to allocate for the
POPUP_MENU_PTR or its internal data structures.
2) There is not enough memory to allocate for the popup
window.
3) There is not enough memory to allocate for the virtual
window.
4) The popup window's size was invalid.
Page 185 The C Window Library Page 185
Problems 1,2, and 3 all are caused by a lack of heap memory.
Problem 4 stems from having invalid parameters in the
PopupCreateMenu(). The arguments that are suspect are the
third, fourth, and fifth arguments. To remedy this problem,
adjust these arguments such that the window can fit on the
screen.
For all of the above conditions, you can get the actual error
code by checking the value of the global integer
window_error_code. If window_error_code is equal to
NO_HEAP_MEM, then condition 1, 2, or 3 has occurred. If it
is equal to BAD_WINDOW_SIZE, then condition 4 has occurred.
If you have a custom window or virtual window opening
function, it is your responsibility to check the error
conditions that may occur, and return correct values or null
pointers if you cannot rectify the error in your custom
routine.
Here is an example:
Example:
int status;
POPUP_MENU_PTR p;
p = PopupCreateMenu(...);
if (p == (POPUP_MENU_PTR)0) {
if (window_error_code == NO_HEAP_MEM)
/* ... Condition 1,2, or 3 occurred */
else
/* Condition 4 occurred */
}
Page 186 The C Window Library Page 186
SELECTING FROM POPUP MENUS
--------------------------
We have now created the popup menu. Now how do we get the
menu manager to act on our popup window? The answer is the
PopupSelectMenu() function.
PopupSelectMenu() function
--------------------------
The PopupSelectMenu() function displays the popup window, and
allows the user to move the highlight bar until he/she has
placed the bar on the desired option, or the user presses a
hotkey to invoke one of the entries.
Before the call to the PopupSelectMenu(), nothing has been
displayed. This means that you can resize the popup window,
change borders, write strings to the popup menus virtual
window, etc. while everything is hidden away from view. The
only time when the popup menu is displayed is when the call
to PopupSelectMenu() is made (or unless you have displayed
the popup window yourself using WindowDisplay()).
A prototype of the call to PopupSelectMenu() is as follows:
int PopupSelectMenu(POPUP_MENU_PTR p, int rank,
unsigned start)
The first argument is the POPUP_MENU_PTR. The second
argument is the rank of the popup window. As with other
windows, the rank determines how the window will be situated
on the screen with respect to the other windows. The last
argument is the number of the menu entry of where the
highlight bar should be situated. Usually this is 1, but
this will give you the option to start on any one of the menu
entries. If the start value is out of bounds (say you have
specified start to be 5 while there are only 4 menu entries)
the menu manager will default to the first menu option.
Now let's put everything together:
#include "menu.h"
int menu_func();
POPUP_MENU_ENTRY menu_items[] = {
" Load F3",1,'L',F3,menu_func,
" Pick Alt-F3",2, 'P',ALTF3,menu_func,
" New" ,3, 'N',0,menu_func,
" Save F2",4, 'S',F2,menu_func,
" Write to ",5, 'W',0,menu_func,
" Directory ",6, 'D',0,menu_func,
" Change Dir" ,7, 'C',0,menu_func,
" OS shell" ,8, 'O',0,menu_func,
Page 187 The C Window Library Page 187
" Quit Alt-X" ,9,'Q',ALTX,menu_func,
CWL_NULL,0};
unsigned int menu_colors[5];
POPUP_MENU_PTR p;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
/* define colors */
menu_colors[ENTRYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[BORDERCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[HOTKEYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[HIGHLIGHTCOLOR] =
CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[UNAVAILCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a POPUP_MENU_PTR */
p = PopupCreateMenu(menu_items,menu_colors, 1,1,6,
POPUPSTATIC,WNULLFN,VWNULLFN);
PopupSelectMenu(p, /* POPUP_MENU_PTR */
1, /* rank of popup window */
1 /* menu entry to start on */
);
}
int menu_func(POPUP_MENU_PTR p, unsigned which)
{
WPOINTER w;
w = WindowInitialize(BORDER,15,15,40,4,
CREATE_VIDEO_ATTRIBUTE(black,white),
CREATE_VIDEO_ATTRIBUTE(black,white),
SINGLEBOX);
WindowOpen(w);
WindowClear(w);
WindowPrintf(w,"You have selected %s",
POPUP_ENTRY_STRING(p,which));
WindowWriteCenterString(w,"Press a key to continue",3);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowFree(w,NOEFFECT);
if (which == 9)
return POPUP_EXIT;
else
return POPUP_CONTINUE;
}
The above example has a call to PopupSelectMenu(). The
arguments passed are p as the POPUP_MENU_PTR, a window rank
Page 188 The C Window Library Page 188
of 1, and a starting position of 1. The POPUP_ENTRY_STRING()
macro in the menu_func() function returns the entry string
for the particualr menu entry. The first argument is the
POPUP_MENU_PTR and the second argument is the entry number.
Values passed to menu function
------------------------------
When a selection is made, the menu manager will call the
function defined for the selection, and pass two arguments to
this function. The first argument passed is the
POPUP_MENU_PTR of the current popup menu and the second
argument is the number of the entry selected. Entry numbers
are numbered from 1 to the highest entry in the menu. For
example, if the " Load F3" entry is selected, the menu
manager will pass the POPUP_MENU_PTR p, and a 1 to func().
If " Pick ALT-F3" is chosen, the menu manager passes a 2 as
the second argument to func() etc.
Values returned to menu manager
-------------------------------
The user function must return an integer back to the menu
manager. If the value returned to the menu manager is
POPUP_EXIT, the menu manager will exit from the current menu
and will return control back to the function that called it.
If the return value is POPUP_CONTINUE, the menu continues to
process selections.
The menu_func() function defined above creates a window,
displays the entry you have chosen, and returns a value back
to the menu manager. If the value is POPUP_EXIT, the menu
manager returns control back to the function that called it.
In this case, main() called PopupSelectMenu(). A return
value of POPUP_CONTINUE will cause the menu manager to let
the user make another selection.
The menu_func() function is a simple implementation. However
your function can do much more sophisticated things,
including opening other popup menus. If another popup menu
is called while in another popup menu, the new popup menu
gets its own menu manager and will not interfere with the
original menu manager. This is good if a menu function will
call another menu function.
Page 189 The C Window Library Page 189
Return Values for PopupSelectMenu()
-----------------------------------
If no errors occurred when PopupSelectMenu() is called the
menu manager returns NO_ERROR when the menu is closed. There
are three possibilities for errors when calling
PopupSelectMenu(). Here are the three possible errors:
1) The popup menus window does not exist.
2) The popup menus window is not opened.
3) The virtual window does not exist.
The first error occurred because the PopupCreateMenu()
function or your custom window function could not initialize
the popup menu window, you inadvertently called WindowFree()
on the popup menu's window, or you are overwriting data with
a stray pointer.
Error 2 can occur if the you inadvertently called
WindowClose() on the popup menu's window, or you are
overwriting data with a stray pointer.
Error 3 can occur if PopupCreateMenu() or your custom virtual
window function could not create the virtual window, or a
stray pointer is overwriting data.
For all of the above conditions, you can get the actual error
code by checking the value of the global integer
window_error_code or by checking the return value of
PopupSelectMenu(). Here is a list of return values and their
corresponding reasons:
Return Value Condition
------------ ---------
BAD_WINDOW 1
WINDOW_NOT_OPEN 2
BAD_V_WINDOW 3
Page 190 The C Window Library Page 190
SETTING OPTIONS IN POPUP MENUS
------------------------------
In addition to setting options using the PopupCreateMenu()
function, you can turn on and off options at any time using
the PopupSetOptions() function.
The PopupSetOptions() function
------------------------------
The PopupSetOptions() function turns either one or more of
the above options on or off. The prototype to the call is as
follows:
int PopupSetOptions(POPUP_MENU_PTR p, int option, int switch)
The first argument is the POPUP_MENU_PTR. The second
argument are the options that you wish to change. The
constants that describe the options are exactly the same as
the ones described in PopupCreateMenu(). The third argument
is whether you want to switch the options on or off.
Here are some sample calls to PopupSetOptions():
a) PopupSetOptions(p,POPUPWRAP,1)
b) PopupSetOptions(p,POPUPSTATIC,1)
c) PopupSetOptions(p,POPUPCONFIRM,1)
d) PopupSetOptions(p,POPUPSTATIC,0)
e) PopupSetOptions(p,POPUPDISPLAY,1)
f) PopupSetOptions(p,POPUPOVERRIDE,1)
g) PopupSetOptions(p,POPUPENHANCEDKEY,1)
The third argument is 1 for "on", 0 for "off".
Example a) sets the highlight bar so that it will wrap.
Example b) informs the menu manager that the menu will not be
hidden when a selection is made.
Example c) will tell the menu manager to call a user defined
function that will inform the menu manager whether to invoke
the selection in the menu.
Example d) Informs the menu manager to hide the menu window
when a menu function is invoked.
Example e) Informs the menu manager not to hide the menu when
control is returned to the function that called
PopupSelectMenu().
Example f) Informs the menu manager to process unavailable
entries. This is useful if you want to set up your own error
routine if the user selects an unavailable entry.
Page 191 The C Window Library Page 191
Example g) imforms the menu manager to distinguish between
normal keys and enhanced keys.
Setting Multiple Options
------------------------
You can also set multiple options with a single call by using
a bitwise OR (|). For example:
PopupSetOptions(p,POPUPWRAP | POPUPSTATIC | POPUPCONFIRM,1)
will set options POPUPWRAP, POPUPSTATIC, and POPUPCONFIRM
defined above.
Setting the PopupSetConfirmFunction()
-------------------------------------
When using the POPUPCONFIRM option, you must also use the
PopupSetConfirmFunction() function to point the menu to the
confirmation function that will be called when a hotkey is
pressed. Here is a prototype of the
PopupSetConfirmFunction():
PopupSetConfirmFunction(POPUP_MENU_PTR p, int (*func)())
where p is the desired popup menu to assign the confirmation
function to, and func is a pointer to a function that will
return a value back to the menu manager that will inform it
to either invoke the option, or ignore the option.
When the confirmation function is called, the menu manager
passes three arguments to func. The prototype for your user
defined function should be as follows:
int my_confirm_func(POPUP_MENU_PTR p, unsigned key,
unsigned sel)
where p is the POPUP_MENU_PTR that is currently being
processed, key is the hotkey that was pressed, and sel is the
selection where the highlight bar is now positioned. The
highlight bar is always positioned on the hotkey selection
even if it may not be invoked. This user defined function
must return a value back to the menu manager. The valid
values that can be returned are POPUP_CONTINUE and
POPUP_DO_CHOICE. If POPUP_CONTINUE is returned, the menu
selection is not invoked, if POPUP_DO_CHOICE is selected, the
menu entry is invoked. Here is an example:
#include "menu.h"
int my_confirm_func();
POPUP_MENU_PTR p;
Page 192 The C Window Library Page 192
/* ... */
main()
{
PopupSetOptions(p,POPUPCONFIRM,1);
PopupSetConfirmFunction(p,my_confirm_func);
/* ... */
}
my_confirm_func(POPUP_MENU_PTR p, unsigned k, unsigned sel)
{
/* ... */
if (k == 'C' || k == 'c' || k == ALTF)
return POPUP_CONTINUE;
else
return POPUP_DO_CHOICE;
}
The above function invokes the menu selection if the hotkey
that was pressed is not a 'C', 'c', or ALT-F.
The confirmation function can do anything, including setting
options in the popup menu, displaying other windows etc.
Return Values for PopupSetOptions() function
--------------------------------------------
You can use the PopupSetOptions() function at any time,
including before calling the PopupSelectMenu() function. If
the option is not a valid option, the function returns
NO_ERROR, but does not change anything. If the switch is not
0 or 1, a 1 is assumed.
If there is an error, the error conditions and reasons are
the same as the PopupSelectMenu() function defined above.
Page 193 The C Window Library Page 193
MAKING MENU ENTRIES AVAILABLE AND UNAVAILABLE
---------------------------------------------
There may be cases when a menu entry should be made
unavailable. The entry shows up in the menu, but it is a
different color than the other entries, and the highlight bar
will just skip over this unavailable entry.
PopupMakeEntryAvailable() and
PopupMakeEntryUnavailable() functions
-------------------------------------
With The C Window Library, you can make entries available and
unavailable at any time. The PopupMakeEntryAvailable() and
the PopupMakeEntryUnavailable() functions perform these
tasks.
A prototype of the call to both of these functions is as
follows:
int PopupMakeEntryAvailable(POPUP_MENU_PTR p, unsigned entry)
int PopupMakeEntryUnavailable(POPUP_MENU_PTR p,
unsigned entry)
The first argument is the POPUP_MENU_PTR. The second
argument is the number of the entry that you wish to change.
Entry numbers range from 1 to the highest entry in the menu.
POPUPOVERRIDE option
--------------------
If the POPUPOVERRIDE option is set (see above), the menu
manager will still process unavailable entries. You must
turn off POPUPOVERRIDE by using the PopupSetOptions()
function if you do not want to process unavailable entries.
Return Values for PopupMakeEntryAvaialble() and
PopupMakeEntryUnavailable() functions
-----------------------------------------------
If there is no error, both of these functions return
NO_ERROR. If there is an error, the following possibilities
can occur:
1) The error can be one of the errors defined above for the
PopupSelectMenu().
2) The menu entry is invalid.
Page 194 The C Window Library Page 194
Refer to the PopupSelectMenu() return values and reasons for
failure defined above for error condition 1). If the error
is 2), check to see if the entry number supplied is valid.
The entry number cannot be < 1 or greater than the number of
selections in the popup menu.
If error 2) has occurred, the PopupMakeEntryAvailable() and
the PopupMakeEntryUnavailable() return MENU_ENTRY_INVALID.
Page 195 The C Window Library Page 195
CHANGING THE MENU ENTRY STRINGS
-------------------------------
There may be times when you want to change a POPUP_MENU_ENTRY
entry_name string. For instance, you may have a menu entry
with the following entry_name:
"Default File Name ABC.DAT"
If the user selects this choice, the file name should change
to another file name the user wants. From there the menu
should reflect the new choice the user has made. Let's say
the user has changed the default file name to DEF.DAT. The
menu then should say:
"Default File Name DEF.DAT"
PopupChangeEntryString() function
---------------------------------
How do you change the entry string? One way is to fool
around with the POPUP_MENU_PTR's structure members, and
change the string yourself. This is not recommended for the
novice to average C programmer, since it is not a good idea
to change the structure members directly without a full
understanding of the structure.
A safer way is to call the PopupChangeEntryString() function.
A prototype of this function is as follows:
PopupChangeEntryString(POPUP_MENU_PTR p, unsigned entry,
char *newstring)
The first argument is the POPUP_MENU_PTR. The second
argument is the number of the entry that you wish to change.
Entry numbers range from 1 to the highest entry in the menu.
The third argument is a pointer to the new character string.
The newstring cannot be longer than the current
POPUP_MENU_ENTRY entry_name string.
Return Values for PopupChangeEntryString() function
---------------------------------------------------
If there is no error, NO_ERROR is returned.
If there is an error, the error conditions and reasons are
the same as the PopupMakeEntryAvailable() function defined
above.
Page 196 The C Window Library Page 196
REDEFINING MENU KEYS
--------------------
Setting Global Key Definitions and
the popup_key_definition Array
----------------------------------
You can redefine the keys used to control moving the
highlight bar, accepting the menu choice, and exiting from
the menu. Here is a list of the default key mapping:
Function Key Constant
-------- --- ------
Move highlight bar up Up Arrow POPUP_UPKEY
Move highlight bar down Down Arrow POPUP_DOWNKEY
Accept Menu Choice Enter POPUP_ACCEPTKEY
Escape Pop-up menu Escape POPUP_QUITKEY
Move To First Menu Item Home POPUP_HOMEKEY
Move to Last Menu Item End POPUP_ENDKEY
Scroll entries up by one
page PgUp POPUP_PAGEUPKEY
Scroll entries down by one
page PgDn POPUP_PAGEDOWNKEY
*Move To Next Popup Menu Unassigned POPUP_RIGHTKEY
*Move to Previous Popup Menu Unassigned POPUP_LEFTKEY
*Escape Pulldown Menu Unassigned POPUP_PULLDOWN_QUITKEY
The global array popup_key_definition contains the values of
the default popup menu key definitions. The names under the
Constant heading are the offsets in the popup_key_definition
array of where the key value for the function is defined.
For instance, the value for the "Move highlight bar up"
function is located at popup_key_definition[POPUP_UPKEY].
You can change the values in popup_key_definition at any
time, but make sure that a definition for "Escape Pop-up
menu" always exists, and that there are no duplicate
definitions (i.e. the "Move highlight bar up" key definition
is the same as the "Move highlight bar down" key definition).
When defining new key values, you should use the values
defined in the keycodes.h header file for non-ascii keys.
* The POPUP_RIGHTKEY, POPUP_LEFTKEY, and the
POPUP_PULLDOWN_QUITKEY definitions only apply to popup
menus that are incorporated in a pulldown menu. See the
section on pulldown menus for more information.
Setting Local Key Definitions
-----------------------------
Another way of redefining menu keys is to load your own array
of key definitions with your desired values, and then calling
the PopupAssignKeys() function. With this method, each menu
can have different key definitions.
Page 197 The C Window Library Page 197
PopupAssignKeys() function
--------------------------
Here is a prototype of the PopupAssignKeys() function:
int PopupAssignKeys(POPUP_MENU_PTR p, unsigned *keys)
where p is the POPUP_MENU_PTR, and keys is an array of key
definitions. Here is a small code example:
#include "menu.h"
unsigned mykeys[NUMPOPUPKEYS] = {CTRLU,CTRLD,RETURN,
ESC,HOME,END,0,0,0,0};
POPUP_MENU_PTR p;
/* Other stuff...*/
main()
{
/* Assume p is initialized */
/* Assigns my key definitions to popup menu p */
PopupAssignKeys(p,mykeys);
}
The constant NUMPOPUPKEYS should be used to make sure that
your array of key definitions is large enough to hold all the
definitions. The above example uses the constants defined
in keycodes.h to assign to the array mykeys. Each position
in the mykeys array uses the default key mapping explained
above. In other words, mykeys[POPUP_UPKEY] is CTRLU, etc.
Return Values for PopupAssignKeys() function
--------------------------------------------
If there is no error, then NO_ERROR is returned.
If there is an error, the error conditions and reasons are
the same as the PopupSelectMenu() function defined above.
Page 198 The C Window Library Page 198
PROCESSING UNDEFINED KEYS
-------------------------
If you are an advanced programmer and/or have experience in
using other window/menu libraries, you may be wondering "how
do I define a function that supplies context-sensitive help
for each POPUP_MENU_ENTRY? There is no structure member in
POPUP_MENU_ENTRY that supplies this". With The C Window
Library, any key that is not recognized by the menu manager
(i.e. the key struck does not invoke a menu option, move the
highlight bar up or down, or ends processing of the menu) can
be processed by calling a user written function. The
WindowGet...() family of functions allowed us to define a
function that will be called if a key that has no current
definition is pressed. For popup menus, we can do the same
thing.
The popup_undef_key function pointer
------------------------------------
The global function pointer, popup_undef_key, can point to a
user written function that will be called when the menu
manager encounters a key that is not defined. The
declaration for popup_undef_key is as follows:
unsigned int (*popup_undef_key)(POPUP_MENU_PTR p,
unsigned int sel,
unsigned int *choice)
The user written function takes three arguments. The first
argument is a pointer to the popup menu that the menu manager
is currently processing. The second argument is an integer
that contains the value of the key that was pressed. The
third argument is a pointer to an integer that will contain
the number of the menu choice to execute. Initially, choice
points to an integer that contains the current menu choice
that the menu highlight bar is situated. For instance, if
the highlight bar is on the first menu choice when an
undefined key is pressed, *choice will be equal to 1. If
popup_undef_key is equal to a Null Function pointer (NULLFN),
no user defined function is called. By default,
popup_undef_key is assigned to NULLFN.
Values returned to menu manager
-------------------------------
If popup_undef_key is assigned to a function, the function
must return an integer back to the menu manager. This
integer value will tell the menu manager how to proceed.
Here is a list of the valid return values that the user
written function can return:
Page 199 The C Window Library Page 199
Return Action to
Value Take
------ ---------
POPUP_CONTINUE No Action. Continue processing the
popup menu.
POPUP_MOVE_UP Move the highlight bar up.
POPUP_MOVE_DOWN Move the highlight bar down.
POPUP_DO_CHOICE Accept and invoke menu entry
assigned to *choice.
POPUP_MOVE_CONTINUE Move the highlight bar to menu entry
assigned to *choice and continue
processing menu.
POPUP_ESCAPE Escape the popup menu.
POPUP_MOVE_HOME Move highlight to first available
menu entry.
POPUP_MOVE_END Move highlight to last available
menu entry.
POPUP_MOVE_PAGEUP Scroll the entries in the popup
window up by one "page" (a page is
the current height of the popup
window).
POPUP_MOVE_PAGEDOWN Scroll the entries in the popup
window down by one "page" (a page is
the current height of the popup
window).
*POPUP_MOVE_LEFT Move to next popup menu.
*POPUP_MOVE_RIGHT Move to previous popup menu.
*POPUP_PULLDOWN_QUIT Escape pulldown menu
A return value of POPUP_CONTINUE is a "do nothing" command to
the menu manager.
If POPUP_DO_CHOICE is returned to the menu manager, the
integer assigned to the parameter *choice is used as the menu
entry to invoke. The highlight bar will automatically be
moved to the menu choice specified, and the menu function
will be called. If POPUP_MOVE_CONTINUE is returned to the
menu manager, the highlight bar will be moved to the entry
specified by the value of *choice, but no function is called.
Return values of POPUP_DO_CHOICE and POPUP_MOVE_CONTINUE only
work when the menu entry specified by *choice is an available
Page 200 The C Window Library Page 200
entry or the POPUPVERRIDE option is on , otherwise the menu
manager just continues processing the popup menu.
* The POPUP_MOVE_RIGHT, POPUP_MOVE_LEFT, and
POPUP_PULLDOWN_QUIT only apply to popup menus that are
incorporated in a pulldown menu system. See the section on
pulldown menus for more information.
Here is an example of using a user defined function for the
undefined keys:
#include "menu.h"
/* Other includes */
int user_func();
main()
{
popup_undef_key = user_func;
/* Other code */
}
unsigned int user_func(POPUP_MENU_PTR p, unsigned sel,
unsigned *choice)
{
switch(sel)
{
case F1:
help(*choice); /* call help function */
return POPUP_CONTINUE; /* return "do nothing" */
case F2:
*choice = 6; /* let menu manager know to do
choice 6 on the menu */
return POPUP_DO_CHOICE; /* Also let menu manager
know we are returning the
"do the function assigned to
*choice" command */
default:
return POPUP_CONTINUE;
/* let menu manager know not to do anything */
}
}
int help(int choice)
{ /* help function */
switch (choice)
{
case 1:
/* do context-sensitive help for entry 1 */
break;
Page 201 The C Window Library Page 201
case 2:
/* do context-sensitive help for entry 2 */
break;
/* do more entries */
/* ... */
}
}
In the above example, if the user hits F1, a help function is
called. If you wanted to know how to incorporate a help
function in the popup menus, here is the way to do it.
If the user hits F2, the integer pointed to by choice is
assigned a 6, and user_func() returns POPUP_DO_CHOICE to the
menu manager. This tells the menu manager to invoke the
function assigned to menu entry 6.
Page 202 The C Window Library Page 202
PRE-INPUT FUNCTION
------------------
With The C Window Library, you can define a function that
will be performed just before the menu manager waits for the
user to enter a keystroke. This function can perform just
about anything.
Setting the global_popup_prefunc function pointer
-------------------------------------------------
The global_popup_prefunc function pointer points to this user
written function. Here is the prototype:
int (*global_popup_prefunc)(POPUP_MENU_PTR p, unsigned *sel)
The arguments that will be passed to your function are the
following:
a) The POPUP_MENU_PTR of the popup menu that called your
function, and
b) A pointer to the number of the selection that the
highlight bar is currently on.
The selection number ranges from 1 to the highest entry
number of the menu.
The pre-input function MUST return a value back to the menu
manager. The return values that can be returned are the same
as the popup_undef_key function described above. If you are
using a version of The C Window Library prior to version 1.5,
you must declare your pre-input function as returning an int,
and you must return a value back to the menu manager.
Versions prior to 1.5 declared the pre-input function as
void.
The POPUP_DO_CHOICE and POPUP_MOVE_CONTINUE return values
will move the highlight bar to the entry number that is
assigned to the *sel argument when the pre-input function has
returned.
By default, global_popup_prefunc points to a NULLFN, and
therefore will not be performed. However, you can implement
pre-input functions depending on the current selection. For
instance, you can write a function that displays extra
information for each entry like so:
#include "menu.h"
char *mess[] = {
" This option saves and loads files",
" This brings you in edit mode",
" This compiles and/or links the current program",
Page 203 The C Window Library Page 203
/* ... More stuff */
};
WPOINTER message_window;
int disp_info();
main()
{
/* ... */
global_popup_prefunc = disp_info;
/* ... */
}
int disp_info(POPUP_MENU_PTR p, unsigned *sel)
{
/* Assume message_window already created and opened */
WindowClear(message_window,
CREATE_VIDEO_ATTRIBUTE(black,white));
WindowWriteString(message_window,mess[*sel-1],1,1);
return POPUP_CONTINUE;
}
For simplicity, the menu definitions are left out of the
preceding code sample. The disp_info displays the
appropriate description in the window message_window.
POPUP_CONTINUE is returned to the menu manager. This informs
the menu manager to continue looking for a keystroke.
Page 204 The C Window Library Page 204
DISPOSING OF POPUP MENUS
------------------------
PopupMenuFree()
---------------
If the popup menu is no longer needed, the PopupMenuFree()
function will dispose of the popup menu and return any memory
allocated to the popup menu, window, and virtual window
memory back to the heap. The call to the function is very
simple:
PopupMenuFree(POPUP_MENU_PTR p)
where p is the POPUP_MENU_PTR to dispose of. Since this
function destroys the POPUP_MENU_PTR p, p must not be used
for any popup menu functions, unless p is pointing to a valid
POPUP_MENU_PTR.
Return Values for PopupMenuFree()
---------------------------------
The return values and the reasons for failure are the same as
PopupSelectMenu().
Page 205 The C Window Library Page 205
BAR MENUS
---------
Description
-----------
A bar menu is a horizontal menu with a list of entries that
are selected by placing a highlight bar on the option and
pressing return, or by invoking the function by using a
hotkey. Bar menus can span several lines. In other words,
menu entries do not have to fit on a single line.
Here is a partial list of the various options you can have
with bar menus:
* Highlight bar wrapping - wrap highlight bar to first or
last option when there are no
more selections.
* Static Menus - menu remains on the screen when
entry is selected.
* Perpetual Menus - menu remain on the screen
regardless of whether the
BarSelectMenu() function
(explained later) is called or
not.
* Hidden (Unavailable) entries - You can make an entry in
the bar menu unavailable
or available at any time.
* Color scheme of the menu - You can customize the color
of the highlight bar, the
hotkey letters, hidden
entries, etc.
* Change entry names - You can safely change the
names displayed in the menu
at any time.
* Use a mouse to select menu entries.
Windows and Virtual Windows
---------------------------
Unlike popup menus, bar menus do not use virtual windows.
Only normal text windows are used.
Page 206 The C Window Library Page 206
CREATING BAR MENUS
------------------
The BAR_MENU_ENTRY structure
----------------------------
The two most important parts of the bar menu are the
BAR_MENU_ENTRY structure and the BAR_MENU_PTR structure. The
BAR_MENU_ENTRY structure is the first step in creating a bar
menu and is discussed here.
Each entry in the bar menu has its own BAR_MENU_ENTRY
structure associated with it. The layout of this structure
is as follows:
char *entry_name -- This is the string that is
displayed in the bar window.
unsigned row -- Row in the window to display
entry_name.
char hotkey_letter -- This is a character in entry_name
that is highlighted from the rest
of the characters in entry_name.
This letter will automatically
invoke the menu function
associated with entry_name.
unsigned ext_hotkey -- This is a secondary hotkey. The
difference between hotkey_letter
and ext_hotkey is that ext_hotkey
can handle keys that are not
ASCII keys (the F keys, Alt and
Ctrl key combinations, etc.).
int (*func)() -- Pointer to function that is
invoked when option is selected.
An array of BAR_MENU_ENTRY's are needed to create all of the
entries on the bar menu. The order of the array elements
determine the order of how they are placed in the window. A
code sample to create an array of BAR_MENU_ENTRY's would be
as follows:
#include "menu.h"
int menu_func();
BAR_MENU_ENTRY bar_items[] = {
"File", /* option name */
1, /* row in window to display option name */
4, /* col. in window to display option */
Page 207 The C Window Library Page 207
'F', /* hotkey letter */
ALTF, /* secondary hotkey */
rt2, /* function to do if chosen */ ,
/* Now define the rest of the BAR_MENU_ENTRY's */
"Edit",1,10,'E',0,menu_func,
"Run",1,17,'R',0,menu_func,
"Compile",1,23,'C',0,menu_func,
"Project",1,33,'P',0,menu_func,
"Options",1,43,'O',0,menu_func,
"Debug",1,53,'D',0,menu_func,
"Break/watch",1,61,'B',0,menu_func,
/* Now terminate with a CWL_NULL option_name */
CWL_NULL};
The first include file, menu.h, is must be included in each
source file that calls menu functions.
As you can see, there is an array of BAR_MENU_ENTRY's, namely
bar_items. Each entry consists of an entry name, row number,
column number, hotkey letter, secondary hotkey, and a
function to call when the entry is selected. The list of
BAR_MENU_ENTRY's MUST be terminated by a CWL_NULL entry name.
There is an alternate method of creating the BAR_MENU_ENTRY
array. Later on, we will discuss creating these entries
dynamically.
Defining Hotkeys
----------------
The hotkey_letter defined in the BAR_MENU_ENTRY structure
must match one of the letters in its corresponding
entry_name. For example, "File", has the hotkey_letter
defined as 'F'. Since 'F' matches the first letter in
"File", the first 'F' in "File" is highlighted. If there is
no match, or if the hotkey_letter is 0, there is no hotkey
associated with this entry. When the menu is displayed,
either the 'f' or 'F' will be accepted as a valid selection
to the entry "File". If there is a BAR_MENU_ENTRY with the
same hotkey letter as another BAR_MENU_ENTRY, the
BAR_MENU_ENTRY closest to the first entry is chosen.
Page 208 The C Window Library Page 208
The ext_hotkey is used if the hotkey cannot be defined as a
single character, or if you want another hotkey definition.
In the above example, the "File" entry_name has an ext_hotkey
of ALTF3 (defined in keycodes.h). If the ALT-F3 key is
pressed, the function rt2() is automatically invoked. If the
ext_hotkey letter is 0, there is no ext_hotkey defined. If
there is a BAR_MENU_ENTRY with the same ext_hotkey as another
BAR_MENU_ENTRY, the BAR_MENU_ENTRY closest to the first entry
is chosen.
Assigning the function to perform
---------------------------------
The func() member is the function that is performed when its
corresponding entry_name is chosen.
This is the first step in completing the total bar menu.
Once the array of BAR_MENU_ENTRY's is created the next step
is to define the colors for each element of the bar menu.
Coloring Bar Menus
------------------
An array of unsigned integers is used to define the color
scheme of the bar menu. Each element of this array stands
for a certain area of the bar menu. Here is a list of array
positions and what they stand for.
Position
Constant
--------
ENTRYCOLOR -- color of the text area of the window.
BORDERCOLOR -- color of the border of the window.
HOTKEYCOLOR -- color of the hotkey letter.
HIGHLIGHTCOLOR -- color of the highlight bar.
UNAVAILCOLOR -- color of the unavailable entries.
Position ENTRYCOLOR of the array defines the color of the
text area of the viewport window. This in turn defines the
color of each entry_name of all of the BAR_MENU_ENTRY's.
Position BORDERCOLOR defines the color of the border of the
window. If the window does not have a border, this attribute
is ignored.
Page 209 The C Window Library Page 209
Position HOTKEYCOLOR defines the color to use for the hotkey
letter. In the above example, the 'L', 'P', 'N', etc. of
each respective entry_name is displayed using this color.
Position HIGHLIGHTCOLOR defines the color used for the
highlight bar. This bar is moved up and down when the user
is making a selection.
Position UNAVAILCOLOR defines the color of the unavailable
menu entries. Whenever a menu entry is unavailable, the
entry_name string displayed takes on this color.
Colors can be created by using the CREATE_VIDEO_ATTRIBUTE()
macro. A code sample to create the colors is as follows:
#include "menu.h"
unsigned int menu_colors[5];
main()
{
{... code ...}
menu_colors[ENTRYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[BORDERCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[HOTKEYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(blue,white);
menu_colors[HIGHLIGHTCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,cyan);
menu_colors[UNAVAILCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
/* rest of the program */
}
Creating bar menu entries dynamically
-------------------------------------
You can create BAR_MENU_ENTRY's dynamically, instead of
defining a pre-determined array of BAR_MENU_ENTRY's explained
previously. Here is an example:
Usual method:
------------
#include "menu.h"
int menu_func();
BAR_MENU_ENTRY bar_items[] = {
"File",1,4,'F',ALTF,menu_func,
"Edit",1,10,'E',0,menu_func,
"Run",1,17,'R',0,menu_func,
Page 210 The C Window Library Page 210
"Compile",1,23,'C',0,menu_func,
"Project",1,33,'P',0,menu_func,
"Options", 1,43,'O',0,menu_func,
"Debug",1,53,'D',0,menu_func,
"Break/watch",1,61,'B',0,menu_func,
CWL_NULL};
Dymamic Method
--------------
#include "menu.h"
#define NUMENTRIES 8
BAR_MENU_ENTRY_PTR menu_array; /* Notice that we have a
pointer to what
will be an array of
BAR_MENU_ENTRY's
*/
BAR_MENU_PTR b;
main()
{
WindowInitializeSystem();
/* Initialize with at least number of total entries */
menu_array = BarAllocate(NUMENTRIES);
/* Call function to create entries
in menu_array sequentially */
BarCreateEntry(menu_array,/* BAR_MENU_ENTRY pointer */
1, /* entry number */
/* The rest of the arguments are just like the old method */
"File", /* menu string */
1, /* row number */
4, /* col. number */
'F', /* hotkey letter */
ALTF, /* secondary hotkey */
menu_func); /* function to perform */
/* do rest of the entries */
BarCreateEntry(menu_array,2,"Edit",1,10,'E',0,menu_func);
BarCreateEntry(menu_array,3,"Run",1,17,'R',0,menu_func);
BarCreateEntry(menu_array,4,"Compfile",1,23,'C',0,
menu_func);
BarCreateEntry(menu_array,5,"Project",1,33,'P',0,menu_func);
BarCreateEntry(menu_array,6,"Options",1,43,'O',0,menu_func);
BarCreateEntry(menu_array,7,"Debug", 1,53,'D',0,menu_func);
BarCreateEntry(menu_array,8,"Break/watch",1,61,'B',0,
menu_func);
/* end all of the menu entries */
BarEntryEnd(menu_array,NUMENTRIES);
Page 211 The C Window Library Page 211
/* create menu */
b = BarCreateMenu(menu_array, /* rest of the arguments */);
/* ... */
/* Dispose of menu entries created */
BarDeallocate(menu_array);
}
The difference between the above method and the method used to
globally initialize an array of BAR_MENU_ENTRY's are the
following:
1) The variable type for menu_array is BAR_MENU_ENTRY_PTR,
not BAR_MENU_ENTRY as the normal method would have done.
2) You must call the BarAllocate() function to allocate space
for the number of entries desired. If you do not call
BarAllocate(), you will surely get a memory overwrite
error. The return value to BarAllocate() must be assigned
to a BAR_MENU_ENTRY_PTR, as the above example shows.
The array of menu entries are allocated from the heap at
runtime, as opposed to the static method which sets up the
memory scheme at link time.
3) The next thing you must do is to fill in the entry
information by calling the BarCreateEntry() function. The
first argument to the BarCreateEntry() function is the
BAR_MENU_ENTRY_PTR. The second argument is the entry
number to assign this information to. The rest of the
arguments are the same order as the usual method i.e.
menu string, row, column, hotkey, etc. BarCreateEntry()
is called for each field desired.
4) The BarEndEntry() function must be called to terminate the
list of entries. The first argument is the
BAR_MENU_ENTRY_PTR, and the second argument is the total
number of entries defined.
5) You should call BarDeallocate() to free the memory
assigned to the array of menu_entries. The only argument
to BarDeallocate() is the BAR_MENU_ENTRY_PTR. Only call
BarDeallocate() after you have called BarMenuFree() or any
function that disposes of the BAR_MENU_PTR.
All of these functions except for BarAllocate() have no
return values. The BarAllocate() function returns a
BAR_MENU_ENTRY_PTR if successful, and a null pointer if
unsuccessful.
Page 212 The C Window Library Page 212
You could also do the following:
#include "menu.h"
#define NUMENTRIES 8
BAR_MENU_ENTRY menu_array[NUMENTRIES+1]; /* We must have at
least 1 more
than the number of entries */
BAR_MENU_PTR b;
main()
{
/* ... */
/* Call function to create entries
in menu_array sequentially */
BarCreateEntry(menu_array, /* BAR_MENU_ENTRY pointer */
1, /* entry number */
/* The rest of the arguments are just like the old method */
"File", /* menu string */
1, /* row number */
4, /* col. number */
'F', /* hotkey letter */
ALTF, /* secondary hotkey */
menu_func); /* function to perform */
/* do rest of the entries */
BarCreateEntry(menu_array,2,"Edit",1,10,'E',0,menu_func);
BarCreateEntry(menu_array,3,"Run",1,17,'R',0,menu_func);
BarCreateEntry(menu_array,4,"Compfile",1,23,'C',0,
menu_func);
BarCreateEntry(menu_array,5,"Project",1,33,'P',0,menu_func);
BarCreateEntry(menu_array,6,"Options",1,43,'O',0,menu_func);
BarCreateEntry(menu_array,7,"Debug", 1,53,'D',0,menu_func);
BarCreateEntry(menu_array,8,"Break/watch",1,61,'B',0,
menu_func);
/* end all of the menu entries */
BarEntryEnd(menu_array,NUMENTRIES);
}
The method above does not call BarAllocate() because the
number of entries was already determined and an array was
already set up at compile time.
BarCreateEntry() is called for each menu entry as before, and
BarEntryEnd() is called to terminate the menu entries.
To use this method, you must declare an array of menu entries
with at least one more than the desired number of entries.
Also note that BarDeallocate() MUST NOT be called because the
array of menu entries was not created with BarAllocate().
Page 213 The C Window Library Page 213
BarCreateMenu() function
------------------------
Now that you have created the BAR_MENU_ENTRY's, and defined
the color scheme, it is time to wrap all of these loose ends
in one package. The next step is to call the BarCreateMenu()
function. This function combines all of the
BAR_MENU_ENTRY's, the colors you have defined, and other
information into one entity called a BAR_MENU_PTR.
A BAR_MENU_PTR is a bar menu structure. Just like a WPOINTER
is a pointer to a window, a BAR_MENU_PTR is used to reference
the bar menu.
A prototype of the call to BarCreateMenu() is as follows:
BAR_MENU_PTR BarCreateMenu(BAR_MENU_ENTRY *b, unsigned *c,
int row, int col, unsigned options,
WPOINTER (*wfunc)())
To illustrate how to use this call, let's use the
BAR_MENU_ENTRY's and colors created in the previous examples:
#include "menu.h"
int menu_func();
BAR_MENU_ENTRY bar_items[] = {
"File",1,4,'F',ALTF,NULLFN,
"Edit",1,10,'E',0,edit,
"Run",1,17,'R',0,NULLFN,
"Compile",1,23,'C',0,NULLFN,
"Project",1,33,'P',0,NULLFN,
"Options", 1,43,'O',0,NULLFN,
"Debug",1,53,'D',0,NULLFN,
"Break/watch",1,61,'B',0,NULLFN,
CWL_NULL};
unsigned int menu_colors[5];
BAR_MENU_PTR b;
main()
{
WindowInitializeSystem(); /* Initialize C Window Library */
/* define colors */
menu_colors[ENTRYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[BORDERCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,white);
Page 214 The C Window Library Page 214
menu_colors[HOTKEYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(blue,white);
menu_colors[HIGHLIGHTCOLOR] =
CREATE_VIDEO_ATTRIBUTE(black,cyan);
menu_colors[UNAVAILCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a BAR_MENU_PTR */
WindowSaveInitial(0); /* Save initial screen */
b = BarCreateMenu(menu_items,menu_colors,1,1,
NO_BAR_OPTIONS,WNULLFN);
/* rest of the code */
}
In the example above there are two function calls that must
be done before calling BarCreateMenu(). The first mandatory
function is WindowInitializeSystem(). The other function
must be WindowSaveInitial() The WindowInitializeSystem()
function must be called to initialize global variables used
by the menu manager. The WindowSaveInitial() function is a
mandatory function because the BarCreateMenu() function
creates windows and assumes that the base screen has been
saved.
The example above declares the variable b to be a
BAR_MENU_PTR. This BAR_MENU_PTR is going to be used to
reference the bar menu throughout the program.
The first argument is a pointer to the first BAR_MENU_ENTRY.
In the above example, menu_items is a pointer to the first
BAR_MENU_ENTRY.
The second argument is a pointer to the array of colors. In
our example, menu_colors is our array of colors.
The third and fourth arguments denote the row and column to
place the upper left hand corner of the bar menu window.
The fifth argument are various bar menu options that are
assigned to the bar menus which are defined below.
Bar Menu Options
----------------
By default the menu manager assumes the following things:
1) The highlight bar does not wrap if the user wants to
move the bar past the last entry, or before the first
entry.
Page 215 The C Window Library Page 215
2) The menu will be hidden from the screen when a
selection is made and will reappear when control is
returned to the menu manager.
3) A function is automatically invoked when the hotkey is
pressed instead of calling a user-defined function
which will tell the menu manager whether the menu entry
is to be executed.
4) The bar menu window is hidden when the menu manager
returns control to the calling function.
5) The highlight bar will skip unavailable entries.
6) The menu manager does not recognize enhanced keys (F11,
F12, etc.).
7) The mouse will not be used to move the highlight bar.
8) Scroll characters will not be displayed on the bar
window. The scroll characters allow the user to scroll
through the options with a mouse.
The last two options are only available if you have a
Microsoft compatible mouse, and the mouse is activated.
If the constant NO_BAR_OPTIONS is used, the assumptions above
are used. If you want to override the above defaults, use
the following options:
Option Name Definition
----------- ----------
BARWRAP Highlight bar wrapping.
BARSTATIC Do not hide menu when selection is
made.
BARCONFIRM Confirmation when selection is made
via hotkey.
BARDISPLAY Display menu even after exit.
BAROVERRIDE Accept Unavailable entries.
BARENHANCEDKEY Recognize enhanced keys.
BARMOUSE Use the mouse to select entries.
As was stated before, the last option, BARMOUSE can only be
used if you have a mouse installed, and the mouse is
activated. More information on these two options is given in
the USING THE MOUSE section.
Page 216 The C Window Library Page 216
By turning the above options "on" the following is assumed:
1) BARWRAP will wrap the highlight bar if the user wants
to move the bar past the last entry or before the first
entry.
2) BARSTATIC will not hide the menu when a selection is
made.
3) BARCONFIRM will call a user-defined function before
invoking the hotkey that was selected. This function
will then return an integer back to the menu manager
informing whether the function selected should be
invoked, or the request should be rejected. There is
more information on this option in the SETTING OPTIONS
IN BAR MENUS section below.
4) BARDISPLAY will not hide the bar window when the menu
manager returns control to the calling function.
5) BAROVERRIDE will make the menu manager accept
unavailable entries.
6) BARENHANCEDKEY will inform the menu manager that
enhanced keys will be recognized.
7) BARMOUSE allows the use of a mouse to make selections.
You can also set multiple options by using a bitwise OR (|).
For example:
b = BarCreateMenu(arg1,arg2,arg3,arg4,
BARWRAP | BARSTATIC | BARCONFIRM,arg5)
will set options BARWRAP, BARSTATIC, and BARCONFIRM defined
above.
The last argument to BarCreateMenu() is defined in the next
sections.
Default Bar Menu Window and Creating Your own Windows
-----------------------------------------------------
The sixth argument to the BarCreateMenu() function is a
pointer to a function that will open a bar menu window. If
this is a NULL function pointer (WNULLFN), the menu manager
will create a window. For most applications, the window that
the menu manager will create is adequate. The menu manager
uses these defaults when making the bar window:
- A bordered window with the border consisting of single
lines (SINGLEBOX).
Page 217 The C Window Library Page 217
- The width of the window is determined by the longest row
of entry names.
If you want to create your own bar menu window, your function
must return a WPOINTER. Inside your function you must create
and open a window using WindowInitialize() and WindowOpen().
For most applications, you do not have to display the window,
instead the menu manager can do the displaying and hiding of
the windows.
Here is an example of creating your own custom window
function:
#include "menu.h"
/* Other includes and menu stuff */
WPOINTER my_open();
BAR_MENU_PTR b;
main()
{
/* Other code */
b = BarCreateMenu(menu_items,menu_colors,1,1,
NO_BAR_OPTIONS,my_open);
/* More code */
}
WPOINTER my_open()
{
WPOINTER w;
w = WindowInitialize(NOBORDER,1,1,80,1,BLACKONWHITE,
BLACKONWHITE,"");
WindowOpen(w);
return w; /* May be null pointer,
but must return to BarCreateMenu() */
}
The example above lets the menu manager know that the window
creation function is a user written function called my_open.
The row, column and height arguments (arguments 3 and 4) of
BarCreateMenu() will be ignored when using a custom window
function. The row and column height parameters used to
create the window in the call to WindowInitialize() in
my_window() will take precedence over the arguments 3 and 4
used in BarCreateMenu().
It is the programmer's responsibility to make sure that the
window that is created is wide and tall enough to hold all of
the menu entries. If not, the results will be unpredictable.
Page 218 The C Window Library Page 218
Accessing bar menu windows
--------------------------
After calling the BarCreateMenu() function, you can access
the bar window by using the BAR_WINDOW() macro. In the above
example, b is the BAR_MENU_PTR and the value of BAR_WINDOW(b)
is a pointer to the bar menu's window. If you want to change
borders move, slide, or anything you can do with normal
windows, you must access the bar window in this way.
For example, if you want to change the border of the bar
window you would do the following:
b = BarCreateMenu(... /* other arguments */ )
/* change border to a double lined box */
WindowDrawBorder(BAR_WINDOW(b),DOUBLEBOX);
The example calls WindowDrawBorder() to change the border of
the bar window.
Warnings
--------
Do not call WindowFree(), WindowClose() on the window of the
bar menu. The menu manager will call these functions when
BarMenuFree() is called. If you close the bar window on an
active menu, the menu manager will assume that the bar window
still exists. Doing so will almost guarantee your
application will bomb out.
Return Values for BarCreateMenu()
---------------------------------
If there are no errors, BarCreateMenu() returns a valid
BAR_MENU_PTR pointer. If there is an error when
BarCreateMenu() is called, a null BAR_MENU_PTR is returned.
Here are the possible reasons why an error has occurred:
1) There is not enough memory to allocate for the
BAR_MENU_PTR or its internal data structures.
2) There is not enough memory to allocate for the bar
window.
3) The bar window's size was invalid.
Problems 1 and 2 all are caused by a lack of heap memory.
Problem 3 stems from having invalid parameters in the
BarCreateMenu(). The arguments that are suspect are the
third and fourth. To remedy this problem, adjust these
arguments such that the window can fit on the screen.
Page 219 The C Window Library Page 219
For all of the above conditions, you can get the actual error
code by checking the value of the global integer
window_error_code. If window_error_code is equal to
NO_HEAP_MEM, then condition 1 or 2 has occurred. If it is
equal to BAD_WINDOW_SIZE, then condition 3 has occurred.
If you have a custom window opening function, it is your
responsibility to check the error conditions that may occur,
and return a correct value or a null pointer if you cannot
rectify the error in your custom routine.
Here is an example:
int status;
BAR_MENU_PTR b;
b = BarCreateMenu(...);
if (b == (BAR_MENU_PTR)0)
{
if (window_error_code == NO_HEAP_MEM)
/* ... Condition 1 or 2 occurred */
else
/* Condition 3 occurred */
}
Page 220 The C Window Library Page 220
SELECTING FROM BAR MENUS
------------------------
We have now created the bar menu. Now how do we get the menu
manager to act on our bar window? The answer is the
BarSelectMenu() function.
BarSelectMenu() function
------------------------
The BarSelectMenu() function displays the bar window, and
allows the user to move the highlight bar until he/she has
placed the bar on the desired entry, or the user presses a
hotkey to invoke one of the entries.
Before the call to the BarSelectMenu(), nothing has been
displayed. This means that you can resize the bar window,
change borders etc. while everything is hidden away from
view. The only time when the bar menu is displayed is when
the call to BarSelectMenu() is made (or unless you have
displayed the bar window yourself using WindowDisplay()).
A prototype of the call to BarSelectMenu() is as follows:
int BarSelectMenu(BAR_MENU_PTR b, int rank, unsigned start)
The first argument is the BAR_MENU_PTR. The second argument
is the rank of the bar window. As with other windows, the
rank determines how the window will be situated on the screen
with respect to the other windows. The last argument is the
number of the menu entry of where the highlight bar should be
situated. Usually this is 1, but this will give you the
option to start on any one of the menu entries. If the start
value is out of bounds (say you have specified start to be 5
while there are only 4 menu entries) the menu manager will
default to the first menu entry.
Now let's put everything together:
#include "menu.h"
int menu_func();
BAR_MENU_ENTRY bar_items[] = {
"File",1,4,'F',ALTF,menu_func,
"Edit",1,10,'E',0,menu_func,
"Run",1,17,'R',0,menu_func,
"Compile",1,23,'C',0,menu_func,
"Project",1,33,'P',0,menu_func,
"Options", 1,43,'O',0,menu_func,
"Debug",1,53,'D',0,menu_func,
"Break/watch",1,61,'B',0,menu_func,
CWL_NULL};
Page 221 The C Window Library Page 221
unsigned int menu_colors[5];
BAR_MENU_PTR b;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
menu_colors[ENTRYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[BORDERCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[HOTKEYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[HIGHLIGHTCOLOR] =
CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[UNAVAILCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a BAR_MENU_PTR */
b = BarCreateMenu(bar_items,menu_colors, 1,1,
BARSTATIC | BARWRAP,WNULLFN);
BarSelectMenu(b,1,1);
}
int menu_func(BAR_MENU_PTR b, unsigned which)
{
WPOINTER w;
w = WindowInitialize(BORDER,15,15,40,4,
CREATE_VIDEO_ATTRIBUTE(black,white),
CREATE_VIDEO_ATTRIBUTE(black,white),
SINGLEBOX);
WindowOpen(w);
WindowPrintf(w,"You have selected %s",
BAR_ENTRY_STRING(b,which));
WindowWriteCenterString(w,"Press a key to continue",3);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowFree(w,NOEFFECT);
if (which == 9)
return BAR_EXIT;
else return BAR_CONTINUE;
}
The above example has a call to BarSelectMenu(). The
arguments passed are b as the BAR_MENU_PTR, a window rank of
1, and a starting position of 1. The BAR_ENTRY_STRING()
macro that is called in menu_func() returns the entry string
of a desired entry in a BAR_MENU_PTR. The first argument is
the BAR_MENU_PTR, and the second argument is the entry number
of the entry desired.
Page 222 The C Window Library Page 222
Values passed to menu function
------------------------------
When a selection is made, the menu manager will call the
function defined for the selection, and pass two arguments to
this function. The first argument passed is the BAR_MENU_PTR
of the current bar menu and the second argument is the number
of the item selected. Item numbers are numbered from 1 to
the highest entry in the menu. For example, if the "File"
entry is selected, the menu manager will pass the
BAR_MENU_PTR b, and a 1 to func(). If "Edit" is chosen, the
menu manager passes a 2 as the second argument to func() etc.
Values returned to menu manager
-------------------------------
The user function must return an integer back to the menu
manager. If the value returned to the menu manager is
BAR_EXIT, the menu manager will exit from the current menu
and will return control back to the function that called it.
If the return value is BAR_CONTINUE, the menu continues to
process selections.
The menu_func() function defined above creates a window,
displays the entry you have chosen, and returns a value back
to the menu manager. If the value is BAR_EXIT, the menu
manager returns control back to the function that called it.
In this case, main() called BarSelectMenu(). A return value
of BAR_CONTINUE will cause the menu manager to let the user
make another selection.
The menu_func() function is a simple implementation. However
your function can do much more sophisticated things,
including opening other bar menus. If another bar menu is
called while in another bar menu, the new bar menu gets its
own menu manager and will not interfere with the original
menu manager. This is good if a menu function will call
another menu function.
Return Values for BarSelectMenu()
---------------------------------
If no errors occurred when BarSelectMenu() is called the menu
manager returns NO_ERROR when the menu is closed. There are
three possibilities for errors when calling BarSelectMenu().
Here are the three possible errors:
1) The bar menu's window does not exist.
2) The bar menu's window is not opened.
The first error occurred because the BarCreateMenu() function
Page 223 The C Window Library Page 223
or your custom window function could not initialize the bar
menu window, you inadvertently called WindowFree() on the bar
menu's window, or you are overwriting data with a stray
pointer.
Error 2 can occur if the you inadvertently called
WindowClose() on the bar menu's window, or you are
overwriting data with a stray pointer.
For all of the above conditions, you can get the actual error
code by checking the value of the global integer
window_error_code or by checking the return value of
BarSelectMenu(). Here is a list of return values and their
corresponding reasons:
Return Value Condition
------------ ---------
BAD_WINDOW 1
WINDOW_NOT_OPEN 2
Page 224 The C Window Library Page 224
SETTING OPTIONS IN BAR MENUS
----------------------------
In addition to setting options using the BarCreateMenu()
function, you can turn on and off options at any time using
the BarSetOptions() function.
The BarSetOptions() function
----------------------------
The BarSetOptions() function turns either one or more of the
above options on or off. The prototype to the call is as
follows:
int BarSetOptions(BAR_MENU_PTR b, int option, int switch)
The first argument is the BAR_MENU_PTR. The second argument
are the options that you wish to change. The constants that
describe the options are exactly the same as the ones
described in BarCreateMenu(). The third argument is whether
you want to switch the options on or off.
Here are some sample calls to BarSetOptions():
a) BarSetOptions(b,BARWRAP,1)
b) BarSetOptions(b,BARSTATIC,1)
c) BarSetOptions(b,BARCONFIRM,1)
d) BarSetOptions(b,BARSTATIC,0)
e) BarSetOptions(b,BARDISPLAY,1)
f) BarSetOptions(b,BAROVERRIDE,1)
g) BarSetOptions(b,BARENHANCEDKEY,1)
The third argument is 1 for "on", 0 for "off".
Example a) sets the highlight bar so that it will wrap.
Example b) informs the menu manager that the menu will not be
hidden when a selection is made.
Example c) will tell the menu manager to call a user defined
function that will inform the menu manager whether to invoke
the selection in the menu.
Example d) Informs the menu manager to hide the menu window
when a menu function is invoked.
Example e) Informs the menu manager not to hide the menu when
control is returned to the function that called
BarSelectMenu().
Example f) Informs the menu manager to process unavailable
entries. This is useful if you want to set up your own error
routine if the user selects an unavailable entry.
Page 225 The C Window Library Page 225
Example g) imforms the menu manager to distinguish between
normal keys and enhanced keys.
Setting Multiple Options
------------------------
You can also set multiple options with a single call by using
a bitwise OR (|). For example:
BarSetOptions(b,BARWRAP | BARSTATIC | BARCONFIRM,1)
will set options BARWRAP, BARSTATIC, and BARCONFIRM defined
above.
Setting the BarSetConfirmFunction()
-----------------------------------
When using the BARCONFIRM option, you must also use the
BarSetConfirmFunction() function to point the menu to the
confirmation function that will be called when a hotkey is
pressed. Here is a prototype of the BarSetConfirmFunction():
int BarSetConfirmFunction(BAR_MENU_PTR b, int (*func)())
where b is the desired bar menu to assign the confirmation
function to, and func is a pointer to a function that will
return a value back to the menu manager that will inform it
to either invoke the option, or ignore the option.
When the confirmation function is called, the menu manager
passes three arguments to func. The prototype for your user
defined function should be as follows:
int my_confirm_func(BAR_MENU_PTR b, unsigned key,
unsigned sel)
where b is the BAR_MENU_PTR that is currently being
processed, key is the hotkey that was pressed, and sel is the
selection where the highlight bar is now positioned. The
highlight bar is always positioned on the hotkey selection
even if it may not be invoked. This user defined function
must return a value back to the menu manager. The valid
values that can be returned are BAR_CONTINUE and
BAR_DO_CHOICE. If BAR_CONTINUE is returned, the menu
selection is not invoked, if BAR_DO_CHOICE is selected, the
menu entry is invoked. Here is an example:
#include "menu.h"
int my_confirm_func();
BAR_MENU_PTR b;
Page 226 The C Window Library Page 226
/* ... */
main()
{
BarSetOptions(b,BARCONFIRM,1);
BarSetConfirmFunction(b,my_confirm_func);
/* ... */
}
my_confirm_func(BAR_MENU_PTR b, unsigned k, unsigned sel)
{
/* ... */
if (k == 'C' || k == 'c' || k == ALTF)
return BAR_CONTINUE;
else
return BAR_DO_CHOICE;
}
The above function invokes the menu selection if the hotkey
that was pressed is not a 'C', 'c', or ALT-F.
The confirmation function can do anything, including setting
options in the bar menu, displaying other windows etc.
Return Values for BarSetOptions() function
------------------------------------------
You can use the BarSetOptions() function at any time,
including before calling the BarSelectMenu() function. If
the option is not a valid option, the function returns
NO_ERROR, but does not change anything. If the switch is not
0 or 1, a 1 is assumed.
If there is an error, the error conditions and reasons are
the same as the BarSelectMenu() function defined above.
Page 227 The C Window Library Page 227
MAKING ENTRIES AVAILABLE AND UNAVAILABLE
----------------------------------------
There may be cases when a menu entry should be made
unavailable. The entry shows up in the menu, but it is a
different color than the other entries, and the highlight bar
will just skip over this unavailable entry.
BarMakeEntryAvailable() and
BarMakeEntryUnavailable() functions
-----------------------------------
With The C Window Library, you can make entries available and
unavailable at any time. The BarMakeEntryAvailable() and the
BarMakeEntryUnavailable() functions perform these tasks.
A prototype of the call to both of these functions is as
follows:
int BarMakeEntryAvailable(BAR_MENU_PTR b, unsigned entry)
int BarMakeEntryUnavailable(BAR_MENU_PTR b, unsigned entry)
The first argument is the BAR_MENU_PTR. The second argument
is the number of the entry that you wish to change. Entry
numbers range from 1 to the highest entry in the menu.
BAROVERRIDE option
------------------
If the BAROVERRIDE option is set (see above), the menu
manager will still process unavailable entries. You must
turn off BAROVERRIDE by using the BarSetOptions() function if
you do not want to process unavailable entries.
Return Values for BarMakeEntryAvaialble() and
BarMakeEntryUnavailable() functions
---------------------------------------------
If there is no error, both of these functions return
NO_ERROR. If there is an error, the following possibilities
can occur:
1) The error can be one of the errors defined above for the
BarSelectMenu().
2) The menu entry is invalid.
Refer to the BarSelectMenu() return values and reasons for
failure defined above for error condition 1). If the error
is 2), check to see if the entry number supplied is valid.
The entry number cannot be < 1 or greater than the number of
Page 228 The C Window Library Page 228
selections in the bar menu.
If error 2) has occurred, the BarMakeEntryAvailable() and the
BarMakeEntryUnavailable() return MENU_ENTRY_INVALID.
Page 229 The C Window Library Page 229
CHANGING THE MENU OPTIONS STRING
--------------------------------
There may be times when you want to change a BAR_MENU_ENTRY
entry_name string. For instance, you may have a menu entry
with the following entry_name:
"Default File Name ABC.DAT"
If the user selects this choice, the file name should change
to another file name the user wants. From there the menu
should reflect the new choice the user has made. Let's say
the user has changed the default file name to DEF.DAT. The
menu then should say:
"Default File Name DEF.DAT"
BarChangeEntryString() function
-------------------------------
How do you change the entry string? One way is to fool
around with the BAR_MENU_PTR's structure members, and change
the string yourself. This is not recommended for the novice
to average C programmer, since it is not a good idea to
change the structure members directly without a full
understanding of the structure.
A safer way is to call the BarChangeEntryString() function.
A prototype of this function is as follows:
int BarChangeEntryString(BAR_MENU_PTR b, unsigned entry,
char *newstring)
The first argument is the BAR_MENU_PTR. The second argument
is the number of the entry that you wish to change. Entry
numbers range from 1 to the highest entry in the menu. The
third argument is a pointer to the new character string.
Remember that the width of the bar menu's window is equal to
the width of the longest line of entry_name entries,
therefore newstring cannot exceed the boundaries of the bar
menu window (unless you will called WindowResizeWidth() or
WindowResizeHeight() to resize the window).
Return Values for BarChangeEntryString() function
-------------------------------------------------
If there is no error, then NO_ERROR is returned.
Page 230 The C Window Library Page 230
If there is an error, the error conditions and reasons are
the same as the BarMakeEntryAvailable() function defined
above.
Page 231 The C Window Library Page 231
REDEFINING THE MENU KEYS
------------------------
Setting Global Key Definitions and
the bar_key_definition Array
----------------------------------
You can redefine the keys used to control moving the
highlight bar, accepting the menu choice, and exiting from
the menu. Here is a list of the default key mapping:
Function Key Constant
-------- --- ------
Move highlight bar right Up Arrow BAR_RIGHTKEY
Move highlight bar left Down Arrow BAR_LEFTKEY
Accept Menu Choice Enter BAR_ACCEPTKEY
Escape Bar menu Escape BAR_QUITKEY
Move To First Menu Item Home BAR_HOMEKEY
Move to Last Menu Item End BAR_ENDKEY
The global array bar_key_definition contains the values of
the default bar menu key definitions. The names under the
Constant heading are the offsets in the bar_key_definition
array of where the key value for the function is defined.
For instance, the value for the "Move highlight bar up"
function is located at bar_key_definition[BAR_RIGHTKEY]. You
can change the values in bar_key_definition at any time, but
make sure that a definition for "Escape Bar menu" always
exists, and that there are no duplicate definitions (i.e.
the "Move highlight bar up" key definition is the same as the
"Move highlight bar down" key definition). When defining new
key values, you should use the values defined in the
keycodes.h header file for non-ascii keys.
Setting Local Key Definitions
-----------------------------
Another way of redefining menu keys is to load your own array
of key definitions with your desired values, and then calling
the BarAssignKeys() function. With this method, each menu
can have different key definitions.
BarAssignKeys() function
------------------------
Here is a prototype of the BarAssignKeys() function:
int BarAssignKeys(BAR_MENU_PTR b, unsigned *keys)
where b is the BAR_MENU_PTR, and keys is an array of key
Page 232 The C Window Library Page 232
definitions. Here is a small code example:
#include "menu.h"
unsigned mykeys[8] = {CTRLR,CTRLL,RETURN,ESC,HOME,END};
BAR_MENU_PTR b;
/* Other stuff...*/
main()
{
/* Assume b is initialized */
BarAssignKeys(b,mykeys); /* Assigns my key
definitions to bar menu b */
}
The above example uses the constants defined in keycodes.h to
assign to the array mykeys. Each position in the mykeys
array uses the default key mapping explained above. In other
words, mykeys[BAR_RIGHTKEY] is CTRLR, etc.
Return Values for BarAssignKeys() function
------------------------------------------
If there is no error, then NO_ERROR is returned.
If there is an error, the error conditions and reasons are
the same as the BarSelectMenu() function defined above.
Page 233 The C Window Library Page 233
PROCESSING UNDEFINED KEYS
-------------------------
If you are an advanced programmer and/or have experience in
using other window/menu libraries, you may be wondering "how
do I define a function that supplies context-sensitive help
for each BAR_MENU_ENTRY? There is no structure member in
BAR_MENU_ENTRY that supplies this". With The C Window
Library, any key that is not recognized by the menu manager
(i.e. the key struck does not invoke a menu option, move the
highlight bar up or down, or ends processing of the menu) can
be processed by calling a user written function. The
WindowGet...() family of functions allowed us to define a
function that will be called if a key that has no current
definition is pressed. For bar menus, we can do the same
thing.
The bar_undef_key function pointer
----------------------------------
The global function pointer, bar_undef_key, can point to a
user written function that will be called when the menu
manager encounters a key that is not defined. The
declaration for bar_undef_key is as follows:
unsigned int (*bar_undef_key)(BAR_MENU_PTR b, unsigned sel,
unsigned int *choice)
The user written function takes three arguments. The first
argument is a pointer to the bar menu that the menu manager
is currently processing. The second argument is an integer
that contains the value of the key that was pressed. The
third argument is a pointer to an integer that will contain
the number of the menu choice to execute. Initially, choice
points to an integer that contains the current menu choice
that the menu highlight bar is situated. For instance, if
the highlight bar is on the first menu choice when an
undefined key is pressed, *choice will be equal to 1. If
bar_undef_key is equal to a Null Function pointer (NULLFN),
no user defined function is called. By default,
bar_undef_key is assigned to NULLFN.
Values returned to menu manager
-------------------------------
If bar_undef_key is assigned to a function, the function must
return an integer back to the menu manager. This integer
value will tell the menu manager how to proceed. Here is a
list of the valid return values that the user written
function can return:
Page 234 The C Window Library Page 234
Return Action to
Value Take
------ ---------
BAR_CONTINUE No Action. Continue processing the bar
menu.
BAR_DO_CHOICE Accept and invoke menu entry assigned
to *choice.
BAR_MOVE_CONTINUE Move the highlight bar to menu entry
assigned to *choice and continue
processing menu.
BAR_ESCAPE Escape the bar menu.
BAR_MOVE_LEFT Move to next bar menu.
BAR_MOVE_RIGHT Move to previous bar menu.
BAR_MOVE_HOME Move highlight to first available menu
entry.
BAR_MOVE_END Move highlight to last available menu
entry.
A return value of BAR_CONTINUE is a "do nothing" command to
the menu manager.
If BAR_DO_CHOICE is returned to the menu manager, the integer
assigned to the parameter *choice is used as the menu entry
to invoke. The highlight bar will automatically be moved to
the menu choice specified, and the menu function will be
called. If BAR_MOVE_CONTINUE is returned to the menu
manager, the highlight bar will be moved to the entry
specified by the value of *choice, but no function is called.
Return values of BAR_DO_CHOICE and BAR_MOVE_CONTINUE only
work when the menu entry specified by *choice is an available
entry or the BAROVERRIDE option is on , otherwise the menu
manager just continues processing the bar menu.
Here is an example of using a user defined function for the
undefined keys:
#include "menu.h"
/* Other includes */
int user_func();
Page 235 The C Window Library Page 235
main()
{
bar_undef_key = user_func;
/* Other code */
}
unsigned int user_func(BAR_MENU_PTR b, unsigned sel,
unsigned *choice)
{
switch(sel)
{
case F1:
help(*choice); /* call help function */
return BAR_CONTINUE; /* return "do nothing" command */
case F2:
*choice = 6; /* do choice 6 on the menu */
return BAR_DO_CHOICE;
default:
return BAR_CONTINUE;
/* let menu manager know not to do anything */
}
}
int help(int choice)
{ /* help function */
switch (choice)
{
case 1:
/* do context-sensitive help for entry 1 */
break;
case 2:
/* do context-sensitive help for entry 2 */
break;
/* do more entries */
/* ... */
}
}
In the above example, if the user hits F1, a help function is
called. If you wanted to know how to incorporate a help
function in the bar menus, here is the way to do it.
If the user hits F2, the integer pointed to by choice is
assigned a 6, and user_func() returns BAR_DO_CHOICE to the
menu manager. This tells the menu manager to invoke the
function assigned to menu entry 6.
Page 236 The C Window Library Page 236
PRE-INPUT FUNCTION
------------------
With The C Window Library, you can define a function that
will be performed just before the menu manager waits for the
user to enter a keystroke. This function can perform just
about anything.
Setting the global_bar_prefunc function pointer
-------------------------------------------------
The global_bar_prefunc function pointer points to this user
written function. Here is the prototype:
int (*global_bar_prefunc)(BAR_MENU_PTR p, unsigned *sel)
The arguments that will be passed to your function are the
following:
a) The BAR_MENU_PTR of the bar menu that called your
function, and
b) A pointer to the number of the selection that the
highlight bar is currently on.
The selection number ranges from 1 to the highest entry
number of the menu.
The pre-input function MUST return a value back to the menu
manager. The return values that can be returned are the same
as the bar_undef_key function described above. If you are
using a version of The C Window Library prior to version 1.5,
you must declare your pre-input function as returning an int,
and you must return a value back to the menu manager.
Versions prior to 1.5 declared the pre-input function as
void.
The BAR_DO_CHOICE and BAR_MOVE_CONTINUE return values will
move the highlight bar to the entry number that is assigned
to the *sel argument when the pre-input function has
returned.
By default, global_bar_prefunc points to a NULLFN, and
therefore will not be performed. However, you can implement
pre-input functions depending on the current selection. For
instance, you can write a function that displays extra
information for each entry like so:
#include "menu.h"
char *mess[] = {
" This option saves and loads files",
" This brings you in edit mode",
" This compiles and/or links the current program",
Page 237 The C Window Library Page 237
/* ... More stuff */
};
WPOINTER message_window;
int disp_info();
main()
{
/* ... */
global_bar_prefunc = disp_info;
/* ... */
}
int disp_info(BAR_MENU_PTR p, unsigned *sel)
{
/* Assume message_window already created and opened */
WindowClear(message_window,
CREATE_VIDEO_ATTRIBUTE(black,white));
WindowWriteString(message_window,mess[*sel-1],1,1);
return BAR_CONTINUE;
}
For simplicity, the menu definitions are left out of the
preceding code sample. The disp_info displays the
appropriate description in the window message_window.
BAR_CONTINUE is returned to the menu manager. This informs
the menu manager to continue looking for a keystroke.
Page 238 The C Window Library Page 238
DISPOSING OF BAR MENUS
----------------------
BarMenuFree() function
----------------------
If the bar menu is no longer needed, the BarMenuFree()
function will dispose of the bar menu and return any memory
allocated to the bar menu, window, and window memory back to
the heap. The call to the function is very simple:
BarMenuFree(BAR_MENU_PTR b)
where b is the BAR_MENU_PTR to dispose of. Since this
function destroys the BAR_MENU_PTR b, b must not be used for
any bar menu functions, unless b is pointing to a valid
BAR_MENU_PTR.
Return Values for BarMenuFree()
-------------------------------
The return values and the reasons for failure are the same as
BarSelectMenu(). Please refer to this section.
Page 239 The C Window Library Page 239
PULLDOWN MENUS
--------------
Description
-----------
A pulldown menu is a combination of popup menus and a bar
menu. The bar menu portion of the pulldown menu acts the
same way as a normal bar menu. However when a choice is made
from the bar menu, a popup menu appears with more options to
choose. An example of a pulldown menu is the integrated
environ- ments of the Quick C and Turbo C compilers.
Most of what was discussed previously will apply to pulldown
menus. Make sure that you have read the sections on popup
menus and bar menus before preceding.
Bar Menu and Popup Menu levels
------------------------------
With pulldown menus there are two levels; the bar menu level
and the popup menu level. When in the bar menu level, no
popup menu's are displayed, and the move right and move left
keys move the highlight bar to the next or previous selection
in the bar menu. When in the popup menu level, the move
right and move left keys not only move the highlight in the
bar menu, but will also display the popup menu associated
with the bar menu option.
Page 240 The C Window Library Page 240
CREATING PULLDOWN MENUS
-----------------------
There are 4 steps that must be done when creating pulldown
menus. They are as follows:
Step 1) Create the bar menu portion by calling
BarCreateMenu().
Step 2) Create each popup menu to be displayed underneath
the bar by calling the PopupCreateMenu()
function.
Step 3) Group all popup menus created in step 2 into an
array of popup menu's.
Step 4) Call PulldownCreateMenu().
For Step 1) the bar menu is created the same way as described
in the Bar Menu section of this manual. The only difference
is that if there is a popup window that will be displayed
under the bar menu option, the function pointer for that
BAR_MENU_ENTRY must be a NULLFN (null integer function
pointer). Otherwise, if there is no popup menu defined for
that bar menu option, the BAR_MENU_ENTRY's function pointer
must point to a valid function. For instance, here is a
sample array of BAR_MENU_ENTRY's used to create the Turbo C
integrated environments bar menu:
BAR_MENU_ENTRY bar_items[] = {
"File", 1,4, 'F',0,NULLFN,
"Edit", 1,10,'E',0,menu_func,
"Run", 1,17,'R',0,NULLFN,
"Compile", 1,23,'C',0,NULLFN,
"Project", 1,33,'P',0,NULLFN,
"Options", 1,43,'O',0,NULLFN,
"Debug", 1,53,'D',0,NULLFN,
"Break/watch",1,61,'B',0,NULLFN,
CWL_NULL};
In the above example, All of the entries have a NULLFN
function pointer except for the "Edit" entry. The entries
with NULLFN function pointers will have popup windows
displayed under them when they are selected. The "Edit"
option will not have a popup menu displayed under it.
Instead, the menu_func() function is performed instead when
"Edit" is chosen.
Step 2) is as described in the Popup windows section.
Page 241 The C Window Library Page 241
Step 3) can be done as follows:
POPUP_MENU_PTR popup_list[8];
main() {
/* ... */
popup_list[0] = PopupCreateMenu(/*..argument list..*/);
popup_list[1] = (POPUP_MENU_PTR)0; /* No popup, so value
must be NULL */
popup_list[2] = PopupCreateMenu(/*..argument list..*/);
popup_list[3] = PopupCreateMenu(/*..argument list..*/);
popup_list[4] = PopupCreateMenu(/*..argument list..*/);
popup_list[5] = PopupCreateMenu(/*..argument list..*/);
popup_list[6] = PopupCreateMenu(/*..argument list..*/);
popup_list[7] = PopupCreateMenu(/*..argument list..*/);
The above example shows each element of popup_list is
assigned to the return value of PopupCreateMenu(), except for
popup_list[1]. Note that popup_list[1] is a null
POPUP_MENU_PTR. Here is the reason. Let's say that there is
an option on the bar menu that DOES NOT have a popup menu
associated with it. In other words, it is just a single
function option, and no sub-functions are possible. The
entry in the array of POPUP_MENU_PTR's that will correspond
to the position of where there is no popup menu should be
NULL. The above example shows that the second POPUP_MENU_PTR
is non-existent (matches with the BAR_MENU_ENTRY called
"Edit", which is the second bar entry).
Once the bar menu and popup menus are created, you can set
options by calling the BarSetOptions() or the
PopupSetOptions() function, assign menu keys using the
BarAssignKeys() or PopupAssignKeys() functions, etc. just as
described earlier in this manual. Remember that a pulldown
menu just incorporates all of your menus into one manageable
entity.
The PulldownCreateMenu() function
---------------------------------
The next step (Step 4) is done by calling the
PulldownCreateMenu() function. This function integrates the
bar menu and the array of popup menus in a single unit. A
pointer to this unit is returned. This pointer is declared
as a PULLDOWN_MENU_PTR. The prototype form the
PulldownCreateMenu() function is as follows:
PULLDOWN_MENU_PTR PulldownCreateMenu(POPUP_MENU_PTR popups[],
BAR_MENU_PTR bar,
Page 242 The C Window Library Page 242
int adjust)
The first argument is a pointer to an array of
POPUP_MENU_PTR's. In the above example, the second argument
is the BAR_MENU_PTR. Here is an example of how to use the
PulldownCreateMenu() function:
#include "menu.h"
BAR_MENU_ENTRY bar_items[] = {
"File", 1,4, 'F',0,NULLFN,
"Edit", 1,10,'E',0,menu_func,
"Run", 1,17,'R',0,NULLFN,
"Compile", 1,23,'C',0,NULLFN,
"Project", 1,33,'P',0,NULLFN,
"Options", 1,43,'O',0,NULLFN,
"Debug", 1,53,'D',0,NULLFN,
"Break/watch",1,61,'B',0,NULLFN,
CWL_NULL};
POPOP_MENU_ENTRY p1[] = {
/* Popup entries */,
CWL_NULL,0 };
POPUP_MENU_ENTRY p2[] = POPUP_NULL_ENTRY; /* This constant
defines an empty
POPUP_MENU_ENTRY */
POPUP_MENU_ENTRY p3[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_ENTRY p4[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_ENTRY p5[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_ENTRY p6[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_ENTRY p7[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_ENTRY p7[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_PTR popup_list[8];
Page 243 The C Window Library Page 243
BAR_MENU_PTR bar;
PULLDOWN_MENU_PTR pull;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
bar = BarCreateMenu(bar_items, { other arguments } );
popup_list[0] = PopupCreateMenu(p1, { other arguments } );
popup_list[1] = p2;
popup_list[2] = PopupCreateMenu(p3, { other arguments } );
popup_list[3] = PopupCreateMenu(p4, { other arguments } );
popup_list[4] = PopupCreateMenu(p5, { other arguments } );
popup_list[5] = PopupCreateMenu(p6, { other arguments } );
popup_list[6] = PopupCreateMenu(p7, { other arguments } );
popup_list[7] = PopupCreateMenu(p8, { other arguments } );
pull = PulldownCreateMenu(popup_list,bar,1);
{...}
}
In the above example, bar is a BAR_MENU_PTR, p1, p2, p3, p4,
etc. are all lists of POPUP_MENU_ENTRY's. The array of
POPUP_MENU_PTR's is called popup_list, and the
PULLDOWN_MENU_PTR is called pull. Please note the use of the
POPUP_NULL_ENTRY constant. Use this constant when
initializing a POPUP_MENU_ENTRY list to no items.
The bar menu is initialized by calling BarCreateMenu() using
bar_items as the list of BAR_MENU_ENTRY's. The
PopupCreateMenu() is called for each member of the popup_list
array. Note that the popup_list[1] is assigned a null
POPUP_MENU_PTR. This indicates that there is no popup menu
for the second bar item ("Edit"). Even though it is not
shown, you should check to see if BarCreateMenu() and all of
the PopupCreateMenu() function calls returned without error.
The call to PulldownCreateMenu() is done with the first
argument being the the pointer to the array of
POPUP_MENU_PTR's, namely popup_list. The second argument is
the BAR_MENU_PTR bar, and the last argument is discussed in
the next section.
Automatic Adjustment of Popup Windows
-------------------------------------
The last argument to PulldownCreateMenu() will inform the
menu manager to adjust all the popup menu window positions,
Page 244 The C Window Library Page 244
so that they fit neatly under the bar menu. If the adjust
argument in PulldownCreateMenu() is a 1, the previous
(row,col) positions of each popup menu window is ignored
(Arguments 3 and 4 of PopupCreateMenu()), and the menu
manager decides where the popup window should be placed on
the screen. Otherwise, if adjust is 0, the previous values
of the (row,col) position of the popup menu is used.
Here is how the menu manager decides where the popup window
should be placed:
a) The first attempt tries to place the left hand corner of
the popup window under the first character of the option
name in the bar menu. If the column on the screen where
we have placed the popup window, plus the popup windows
width does not exceed the width of the bar, then we have
found a "good" position for the popup window, if not then
do step b).
b) We place the upper right hand corner of the popup window
underneath the last column of the bar menu's window. If
the upper left-hand corner of the popup window can be
placed in a screen column greater than or equal to 1,
then we have found the "good" position. If the upper
left-hand corner cannot be placed in column 1 then do
step c).
c) Place the upper left hand corner of the popup window at
the first column of the bar menu window. If this does
not work then do step d).
d) place the popup window in column 1 of the screen.
Here are a few examples of the above scenarios:
1)
-------------------------------------------------------------
| File Edit Compile Options Project |
| |
------------------------------------------------------------
| |
|Condition a)|
| worked! |
| |
|------------|
Page 245 The C Window Library Page 245
2a)
----------------------------------------------------
| File Edit Compile Options Project |
| |
------------------------------------------------------------
| |
| Too wide! option a) failed! |
| |
| Try option b) |
| |
|--------------------------------|
2b)
-------------------------------------------------------------
| File Edit Compile Options Project |
| |
-------------------------------------------------------------
| |
| option b) worked! |
| |
|--------------------------------|
In the first example, 1), the assumption is that the menu
manager tries to place a popup window underneath the "File"
in the bar menu. It satisfies condition a), so we have found
a good position.
In the second example, 2a), the assumption is that the menu
manager is trying to place a popup window under the "Compile"
in the bar menu. The first attempt fails because the popup
window is too wide to be contained entirely in the bar menu.
We then try again to see if condition b) can be satisfied.
Example 2b) shows that we can place the popup window
according to condition b), and we have found a good
condition.
The other conditions, c) and d) should be self-explanatory at
this point.
Remember, if you do not like the way the menu manager selects
the window position, you can either
a) specify the row and column positions of each popup menu
window yourself when calling PopupCreateMenu(), and then
calling PulldownCreateMenu() with a 0 (no adjustment) as
the third argument or
b) Let the menu manager decide where to put the windows, and
then adjust the positions yourself by calling
WindowMove().
Page 246 The C Window Library Page 246
Return values for PulldownCreateMenu()
--------------------------------------
If there is no error, PulldownCreateMenu() returns a valid
PULLDOWN_MENU_PTR.
If there is an error, PulldownCreateMenu() returns a null
PULLDOWN_MENU_PTR.
Here are the possible reasons why an error has occurred:
1) There was not enough memory to allocate for the
PULLDOWN_MENU_PTR or its internal data structures.
2) The window for the bar menu did not exist.
The first error results from a lack of heap memory. If this
error occurs, the global integer window_error_code will be
set to NO_HEAP_MEM.
If the second error occurs, this is an indication that the
BAR_MENU_PTR was not created properly. Check the return
values for BarCreateMenu() if this happens. The
window_error_code is set to BAD_WINDOW if this error occurs.
There is no check to see if the POPUP_MENU_PTR's are valid.
It is conceivable that there may be some entries on the bar
that do not have popup menu's under them. Therefore no check
can be made for valid POPUP_WINDOW_PTR's. It is the
programmer's responsibility to check for invalid
POPUP_MENU_PTR's when creating the popup menus.
Page 247 The C Window Library Page 247
SELECTING FROM PULLDOWN MENUS
-----------------------------
The PulldownSelectMenu() function
---------------------------------
The PulldownSelectMenu() allows selection from a pulldown
menu. This function has 6 arguments. The prototype to this
function is as follows:
int PulldownSelectMenu(PULLDOWN_MENU_PTR pull, int barrank,
unsigned barstart, int *poprank,
unsigned *popstart, int imm)
The first argument is a pointer to the PULLDOWN_MENU_PTR.
The second argument is the window rank of the bar menu
window. The third argument is the menu option where the bar
menu should start beginning processing. If the option is
invalid or unavailable, the starting entry is the first
available entry or the first entry if the BAROVERRIDE option
is on for the bar menu.
The fourth argument is an array of window ranks for each
popup menu's window. This array will correspond to each of
the popup menu's windows, including null popup menus.
Example:
int ranks[] = {1,1,1,1,1,1,1,1};
unsigned start[] = {1,1,1,1,1,1,1,1};
main() {
/* ... */
PulldownSelectMenu(pull,1,1,ranks,start,1);
}
The fifth argument is an array of starting entry numbers for
each popup menu. This array will correspond to each of the
popup menus, including NULL popup menus. The previous
example illustrates how this could be done.
Immediate Mode
--------------
The last argument to PulldownSelectMenu() determines whether
the menu will start in immediate mode. Immediate mode will
display the bar menu, and will also display the popup menu
defined for the bar option. If immediate mode is desired,
the last argument is a 1, otherwise it is a 0.
Page 248 The C Window Library Page 248
Values passed to the selected menu function
-------------------------------------------
When a selection is made, the menu manager will call the
function defined for the selection, and pass five arguments
to this function. The first argument passed is the
PULLDOWN_MENU_PTR of the current pulldown menu. The second
argument is the BAR_MENU_PTR of the pulldown menu. The third
argument is the POPUP_MENU_PTR of the selected entry. If
there is no popup menu, the value passed for this argument
is a NULL pointer. The fourth argument is the number of the
item selected on the bar menu. The fifth argument is the
number of the item selected on the popup menu.
Values returned to the menu manager
-----------------------------------
Your function must return a value back to the menu manager.
There are two possible return values, PULLDOWN_EXIT and
PULLDOWN_CONTINUE.
The PULLDOWN_EXIT return value will cause the menu manager to
close both the popup menu window (if one was displayed), and
the bar menu. Then control is returned back to the function
that called PulldownSelectMenu().
The PULLDOWN_CONTINUE return value will cause the menu
manager to continue processing the pulldown menu without
closing the popup window (if one was displayed).
If the return value is not one of the ones mentioned above,
PULLDOWN_CONTINUE is assumed.
Return Values for PulldownSelectMenu()
--------------------------------------
If there are no errors, PulldownSelectMenu() returns NO_ERROR.
If the bar menu window does not exist, PulldownSelectMenu()
immediately returns with BAD_WINDOW.
If the bar menu window is not open, PulldownSelectMenu()
immediately returns with WINDOW_NOT_OPEN.
Page 249 The C Window Library Page 249
REDEFINING KEY DEFINITIONS
--------------------------
The bar menu key definitions are invoked when the pulldown
menu is at the bar menu level. The popup menu keys are
invoked when the pulldown menu is at the popup menu level.
If the bar option does not have a popup menu associated with
it, the bar menu keys are always used.
Page 250 The C Window Library Page 250
REDEFINING KEY DEFINITIONS FOR POPUP MENUS
------------------------------------------
Setting Popup Menu Global Key Definitions
-----------------------------------------
In the previous sections on popup menus, there was a global
array of key definitions used for popup menus. Recall that
there were 3 key definitions that were not assigned. These
definitions were POPUP_RIGHTKEY, POPUP_LEFTKEY, and
POPUP_PULLDOWN_QUIT. When a popup menu is incorporated into
a pulldown menu (after the PulldownCreateMenu() is called),
the global array popup_key_definition is assigned the default
values for these definitions. Here are the default values
for the popup portion of the pulldown menu:
Function Key Constant
-------- --- ------
Move highlight bar up Up Arrow POPUP_UPKEY
Move highlight bar down Down Arrow POPUP_DOWNKEY
Accept Menu Choice Enter POPUP_ACCEPTKEY
Escape Pop-up menu Escape POPUP_QUITKEY
Move To First Menu Item Home POPUP_HOMEKEY
Move to Last Menu Item End POPUP_ENDKEY
Move To Next Popup Menu Right Arrow POPUP_RIGHTKEY
Move to Previous Popup Menu Left Arrow POPUP_LEFTKEY
Escape Pulldown Menu Unassigned POPUP_PULLDOWN_QUITKEY
The global array popup_key_definition contains the values of
the default popup menu key definitions. The names under the
Constant heading are the offsets in the popup_key_definition
array of where the key value for the function is defined.
For instance, the value for the "Move highlight bar up"
function is located at popup_key_definition[POPUP_UPKEY].
You can change the values in popup_key_definition at any
time, but make sure that a definition for "Escape Pop-up
menu" and/or "Escape Pulldown Menu" always exists, and that
there are no duplicate definitions (i.e. the "Move highlight
bar up" key definition is the same as the "Move highlight bar
down" key definition). When defining new key values, you
should use the values defined in the keycodes.h header file
for non-ascii keys.
Also note that popup_key_definition[POPUP_PULLDOWN_QUITKEY]
is not assigned. Since the key that is usually used to quit
a pulldown menu is the Escape (ESC) key, and this definition
conflicts with the "Escape Popup menu", it is better to let
the programmer change the definition explicitly.
Page 251 The C Window Library Page 251
Setting Popup Menu Local Definitions
------------------------------------
You can use the PopupAssignKeys() function explained in the
REDEFINING MENU KEYS section to redefine the popup menu keys
for each popup menu.
Page 252 The C Window Library Page 252
REDEFINING KEY DEFINITIONS FOR THE BAR MENU
-------------------------------------------
Setting bar menu global key definitions
---------------------------------------
You can redefine the keys used to control moving the
highlight bar, accepting the menu choice, and exiting from
the menu. Here is a list of the default key mapping:
Function Key Constant
-------- --- ------
Move highlight bar right Up Arrow BAR_RIGHTKEY
Move highlight bar left Down Arrow BAR_LEFTKEY
Accept Menu Choice Enter BAR_ACCEPTKEY
Escape Bar menu or Escape BAR_QUITKEY
Escape Pulldown Menu
Move To First Menu Item Home BAR_HOMEKEY
Move to Last Menu Item End BAR_ENDKEY
The global array bar_key_definition contains the values of
the default bar menu key definitions. The names under the
Constant heading are the offsets in the bar_key_definition
array of where the key value for the function is defined.
For instance, the value for the "Move highlight bar up"
function is located at bar_key_definition[BAR_RIGHTKEY]. You
can change the values in bar_key_definition at any time, but
make sure that a definition for "Escape Bar menu" always
exists, and that there are no duplicate definitions (i.e.
the "Move highlight bar up" key definition is the same as the
"Move highlight bar down" key definition). When defining new
key values, you should use the values defined in the
keycodes.h header file for non-ascii keys.
Note that "Escape Bar Menu" will also escape the pulldown
menu.
Setting Bar Menu Local definitions
----------------------------------
You can use the BarAssignKeys() function to redefine the bar
menu keys.
Page 253 The C Window Library Page 253
PROCESSING UNDEFINED POPUP MENU KEYS
------------------------------------
Processing undefined keys is the same for regular popup
menus, except that there are 3 new return values that can be
used for popup menus that are incorporated in pulldown menus.
The popup_undef_key function pointer acts the same way as
described previously. Here are the possible values that the
function pointed to by popup_undef_key must return:
Return Action to
Value Take
------ ---------
POPUP_CONTINUE No Action. Continue processing the
popup menu.
POPUP_MOVE_UP Move the highlight bar up.
POPUP_MOVE_DOWN Move the highlight bar down.
POPUP_DO_CHOICE Accept and invoke menu entry
assigned to *choice.
POPUP_MOVE_CONTINUE Move the highlight bar to menu
entry assigned to *choice and
continue processing menu.
POPUP_ESCAPE Escape the popup menu.
POPUP_MOVE_HOME Move highlight to first available
menu entry.
POPUP_MOVE_END Move highlight to last available
menu entry.
POPUP_MOVE_PAGEUP Scroll the entries in the popup
window up by one "page" (a page is
the current height of the popup
window).
POPUP_MOVE_PAGEDOWN Scroll the entries in the popup
window down by one "page" (a page is
the current height of the popup
window).
POPUP_MOVE_LEFT Move to next popup menu.
POPUP_MOVE_RIGHT Move to previous popup menu.
POPUP_PULLDOWN_QUIT Escape pulldown menu
Please note the new return values POPUP_MOVE_LEFT,
POPUP_MOVE_RIGHT, and POPUP_PULLDOWN_QUIT.
Page 254 The C Window Library Page 254
PROCESSING UNDEFINED BAR MENU KEYS
----------------------------------
Here are the return values that the function pointed to by
bar_undef_key must return.
Return Action to
Value Take
------ ---------
BAR_CONTINUE No Action. Continue processing the bar
menu.
BAR_DO_CHOICE Accept and invoke menu entry assigned
to *choice, or display popup menu
underneath bar entry.
BAR_MOVE_CONTINUE Move the highlight bar to menu entry
assigned to *choice and continue
processing menu.
BAR_ESCAPE Escape the bar menu (or pulldown menu).
BAR_MOVE_LEFT Move to next bar menu entry.
BAR_MOVE_RIGHT Move to previous bar menu entry.
BAR_MOVE_HOME Move highlight to first available menu
entry.
BAR_MOVE_END Move highlight to last available menu
entry.
Please note that BAR_DO_CHOICE will either do the function
assigned to the bar entry assigned to *choice, or display the
popup menu underneath the bar menu entry assigned to *choice.
Page 255 The C Window Library Page 255
DISPOSING OF PULLDOWN MENUS
---------------------------
There are two functions that are used to dispose of pulldown
menus. The first is the PulldownMenuFree() function.
The PulldownMenuFree() function
-------------------------------
The PulldownMenuFree() function disposes of the
PULLDOWN_MENU_PTR and returns memory allocated back to the
heap. The bar menu and the popup menus associated with the
pulldown menu remain intact.
Here is a prototype of the call to PulldownMenuFree():
int PulldownMenuFree(PULLDOWN_MENU_PTR pull)
The PulldownMenuFreeAll() function
----------------------------------
To dispose of the pulldown menu, the bar menu, and all of the
popup menus, use the PulldownMenuFreeAll() function. Here is
a prototype:
int PulldownMenuFreeAll(PULLDOWN_MENU_PTR pull)
Page 256 The C Window Library Page 256
SUMMARY OF PULLDOWN MENUS
-------------------------
A pulldown menu is:
1) Made up of a bar menu and popup menus.
2) Consists of two levels, namely the bar menu level and
the popup menu level.
3) The bar menu level uses the bar menu key definitions,
while the popup menu level uses the popup menu key
definitions.
4) The popup menus are initialized by using an array of
POPUP_MENU_PTR's. The order of where the popup menus
are defined in this array corresponds to each of the
bar menu options.
5) A bar menu option may or may not have a popup menu
defined for it.
6) When initializing a pulldown menu, you can allow the
menu manager to position the popup windows under the
bar menu, or you can specify your own positions on the
screen for the popup menu windows.
7) When the menu manager calls the user written function
the PULLDOWN_MENU_PTR, BAR_MENU_PTR, POPUP_MENU_PTR,
the number of the bar entry selected, and the number of
the popup selection are passed to the user function.
If there is no popup menu, the POPUP_MENU_PTR passed is
a null, and the popup selection number is 0.
8) You can open a pulldown menu from the bar level, or
from the pull down level by calling
PulldownSelectMenu().
9) You can close a pulldown menu in two ways: by just
disposing of the PULLDOWN_MENU_PTR by calling
PulldownMenuFree(), or disposing of all menus used to
create the pulldown menu by calling
PulldownMenuFreeAll().
Page 257 The C Window Library Page 257
EXAMPLE OF PULLDOWN MENU SYSTEM
-------------------------------
Here is an example of a pulldown menu system. This program
emulates the Turbo C integrated environment.
#include "menu.h"
#define BLACKONWHITE CREATE_VIDEO_ATTRIBUTE(white,black)
int menu_routine();
POPUP_MENU_ENTRY menu_items1[] = {
" Load F3",1,'L',F3,menu_routine,
" Pick Alt-F3",2, 'P',ALTF3,menu_routine,
" New" ,3, 'N',0,menu_routine,
" Save F2",4, 'S',F2,menu_routine,
" Write to ",5, 'W',0,menu_routine,
" Directory ",6, 'D',0,menu_routine,
" Change Dir" ,7, 'C',0,menu_routine,
" OS shell" ,8, 'O',0,menu_routine,
" Quit Alt-X" ,9,'Q',ALTX,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items3[] = {
" Run Ctrl-F9 ",1,'R',CTRLF9,menu_routine,
" Program reset Ctrl-F2 ",2,'P',CTRLF2,menu_routine,
" Go to Cursor F4 ",3,'G',F4,menu_routine,
" Trace into F7 ",4,'T',F7,menu_routine,
" Step over F8 ",5,'S',F8,menu_routine,
" User screen Alt-F5 ",6,'U',ALTF5,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items4[] = {
" Compile to OBJ ",1,'C',0,menu_routine,
" Make EXE file ",2,'M',0,menu_routine,
" Link EXE file ",3,'L',0,menu_routine,
" Build all ",4,'B',0,menu_routine,
" Primary C file: ",5,'P',0,menu_routine,
" Get info ",6,'G',0,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items5[] = {
" Project Name ",1,'P',0,menu_routine,
" Break make on ",2,'B',0,menu_routine,
" Auto dependencies ",3,'A',0,menu_routine,
" Clear project ",4,'C',0,menu_routine,
" Remove messages ",5,'R',0,menu_routine,
CWL_NULL,0};
Page 258 The C Window Library Page 258
POPUP_MENU_ENTRY menu_items6[] = {
" Compiler ",1,'C',0,menu_routine,
" Linker ",2,'L',0,menu_routine,
" Environment ",3,'E',0,menu_routine,
" Directories ",4,'D',0,menu_routine,
" Arguments ",5,'A',0,menu_routine,
" Save Options ",6,'S',0,menu_routine,
" Retrieve options ",7,'R',0,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items7[] = {
" Evaluate Ctrl-F4 ",1,'E',CTRLF4,menu_routine,
" Call Stack Ctrl-F3 ",2,'C',CTRLF3,menu_routine,
" Find Function ",3,'F',0,menu_routine,
" Refresh display ",4,'R',0,menu_routine,
" Display swapping Smart ",5,'D',0,menu_routine,
" Source debugging ",6,'S',0,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items8[] = {
" Add watch Ctrl-F7 ",1,'A',CTRLF7,menu_routine,
" Delete watch ",2,'D',0,menu_routine,
" Edit Watch ",3,'E',0,menu_routine,
" Remove all watches ",4,'R',0,menu_routine,
" Toggle breakpoint Ctrl-F8 ",6,'T',CTRLF8,menu_routine,
" Clear all breakpoints ",7,'C',0,menu_routine,
" View next breakpoint ",8,'V',0,menu_routine,
CWL_NULL,0};
BAR_MENU_ENTRY bar_items[] = {
"File",1,4,'F',0,NULLFN,
"Edit",1,10,'E',0,menu_routine,
"Run",1,17,'R',0,NULLFN,
"Compile",1,23,'C',0,NULLFN,
"Project",1,33,'P',0,NULLFN,
"Options", 1,43,'O',0,NULLFN,
"Debug",1,53,'D',0,NULLFN,
"Break/watch",1,61,'B',0,NULLFN,
CWL_NULL};
POPUP_MENU_ENTRY *pentry[] = {menu_items1,
POPUP_NULL_ENTRY,
menu_items3,
menu_items4,
menu_items5,
menu_items6,
menu_items7,
menu_items8};
unsigned menu_colors[5]; /* Menu colors */
BAR_MENU_PTR bar; /* Pointer to bar menu */
POPUP_MENU_PTR popups[8]; /* Array of pointers to
Page 259 The C Window Library Page 259
popup menus */
PULLDOWN_MENU_PTR pull; /* Pointer to pulldown menu */
WPOINTER my_open(); /* Pointer to custom bar
window open function */
unsigned int popuprank[] = {1,1,1,1,1,1,1,1}; /* Ranks */
int popupstart[] = {1,1,1,1,1,1,1,1}; /* Starting option
for each popup menu */
int height[] = {9,0,6,6,5,7,6,8}; /* height of each window */
WPOINTER pw; /* Misc. windows, not part of menu
system */
char *line =
"─────────────────────────────"; /* Horizontal line */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
pw = WindowInitialize(BORDER,5,10,70,5,BLACKONWHITE,
BLACKONWHITE,SINGLEBOX);
WindowOpen(pw);
/* define colors */
menu_colors[0] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[1] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[2] = CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[3] = CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[4] = CREATE_VIDEO_ATTRIBUTE(white,black);
bar = BarCreateMenu(bar_items,menu_colors,6,1,
BARWRAP | BARSTATIC, my_open);
/* Now loop to create all popup menus
Be careful and assign NULL to the second popup menu */
for (i=0; i<8; i++) /* Loop for all popup menus */
{
if (pentry[i] != POPUP_NULL_ENTRY) /* Skip over NULL */
{
popups[i] =
PopupCreateMenu(pentry[i],
menu_colors,
1,
1,
height[i],
POPUPWRAP | POPUPSTATIC,
WNULLFN,
VWNULLFN);
}
else
popups[i] = (POPUP_MENU_PTR)0; /* Make this a null
POPUP_MENU_PTR */
Page 260 The C Window Library Page 260
} /* end for (i=0 ... */
VirtualWriteString(POPUP_VIRTUAL_WINDOW(popups[7]),line,
5,1);
/* hide 2nd and 3rd entries in */
PopupMakeEntryUnavailable(popups[6],2);
PopupMakeEntryUnavailable(popups[6],3);
/* puit override option on number 6 */
PopupSetOptions(popups[6],POPUPOVERRIDE,1);
/* create pulldown menu */
pull = PulldownCreateMenu(popups,bar,1);
/* get the menu options */
PulldownSelectMenu(pull,1,1,popuprank,popupstart,1);
/* dispose of menu */
PulldownMenuFree(pull);
}
int menu_routine(PULLDOWN_MENU_PTR p, BAR_MENU_PTR b,
POPUP_MENU_PTR pop,
unsigned int hs, unsigned int vs)
{
int ch;
WindowClear(pw);
WindowPrintf(pw,
"You have selected bar option %s\npopup option %s\n",
BAR_ENTRY_STRING(b,hs),POPUP_ENTRY_STRING(pop,vs));
WindowWriteCenterString(pw,"Press Escape to Quit",3);
WindowWriteCenterString(pw,
"Press any other key to continue...",4);
WindowDisplay(pw,1,NOEFFECT);
ch = GET_KEY();
WindowHide(pw,NOEFFECT);
if (ch == ESC)
return PULLDOWN_EXIT;
return PULLDOWN_CONTINUE;
}
WPOINTER my_open() /* Custom window open function */
{
WPOINTER w;
w = WindowInitialize(NOBORDER,1,1,80,1,BLACKONWHITE,
BLACKONWHITE,"");
WindowOpen(w);
return w;
}
Page 261 The C Window Library Page 261
MISCELLANEOUS FUNCTIONS
-----------------------
There are other functions in The C Window Library that you
can use without defining windows.
SETTING AND CHECKING VIDEO PAGES
--------------------------------
The following functions sets and checks video pages. Your
video setup must support multiple video pages for the
examples given in this section to work. Please refer to page
5 for a discussion of video adapters and the number of pages
each will support.
CheckVideoPage()
----------------
This function checks to see if the video page is valid. Here
is the prototype:
int CheckVideoPage(int page)
If page is valid, CheckVideoPage() returns NO_ERROR. If it
is not, the return value is INVALID_PAGE.
Example:
#include "window.h"
main()
{
int i;
WindowInitializeSystem();
for (i=0;i<8;i++)
{
if (CheckVideoPage(i) == NO_ERROR)
printf("\nValid video page #%d",i);
else
printf("\nInvalid video page #%d",i);
}
}
Page 262 The C Window Library Page 262
SetActiveVideoPage() function
-----------------------------
The SetActiveVideoPage() function sets the active video page.
Here is a prototype:
int SetActiveVideoPage(int page)
Any windows initialized with WindowInitialize() will have its
output directed to the current active video page on
initialization. This function DOES NOT change the visible
display page.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w1, w2;
main()
{
WindowInitializeSystem();
/* Save Base Screen for video pages 0 and 1 */
WindowSaveInitial(0);
WindowSaveInitial(1);
/* Set the active video page */
SetActiveVideoPage(0);
w1 = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
SetActiveVideoPage(1);
w2 = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
}
The above example shows two windows, w1 and w2, being open on
different video pages. Please note the two calls to
WindowSaveInitial(). The first saves the base screen on
video page 0, and the second call saves the initial screen on
page 1. The first call to SetActiveVideoPage() sets the
active video page to page 0. This is usually the active
video page on startup. Since the active page is 0, w1 is
opened with page 0 as its video page. The second call to
SetActiveVideoPage() makes page 1 the active page, therefore
w2 is initialized to send its output to video page 1.
If there are no errors, SetActiveVideoPage() returns
NO_ERROR.
If there are errors, SetActiveVideoPage() returns
INVALID_PAGE if the video page is invalid.
Page 263 The C Window Library Page 263
SetVisibleVideoPage() function
------------------------------
The SetVisibleVideoPage() function sets the visible video
page. Here is a prototype:
int SetVisibleVideoPage(int page)
The visible video page is the page displayed on the screen.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w1,w2;
main()
{
WindowInitializeSystem();
/* Make sure video page is 0 */
SetVisibleVideoPage(0);
SetActiveVideoPage(0);
/*Save Base screen for video pages 0 and 1 */
WindowSaveInitial(0);
WindowSaveInitial(1);
/* Initialize Windows */
w1 = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
SetActiveVideoPage(1);
w2 = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
WindowOpen(w1);
WindowOpen(w2);
WindowWriteString(w1,"This is window 1 on page 0",1,1);
WindowWriteString(w2,"This is window 2 on page 1",1,1);
/* Display video page 0 */
WindowDisplay(w1,1,NOEFFECT);
GET_KEY();
/* Change to video page 1 and display */
SetVisibleVideoPage(1);
WindowDisplay(w2,1,NOEFFECT);
GET_KEY();
/* Reset to page 0 */
SetVisibleVideoPage(0);
}
The example above initializes two windows. w1 is initialized
on page 0 and w2 is initialized on page 1. Also note that
Page 264 The C Window Library Page 264
there are two calls to WindowSaveInitial(), one for page 0
and another for page 1. The first window displayed is w1.
Once a key is pressed the visible page is switched to page 1
by calling SetVisibleVideoPage(). The last line of the
program sets the visible page back to page 0. You should do
this on exit of any program that changes video pages.
If there are no errors, SetVisibleVideoPage() returns
NO_ERROR.
If there are errors, SetVisibleVideoPage() returns
INVALID_PAGE if the video page is invalid.
Page 265 The C Window Library Page 265
GENERAL STRING WRITING FUNCTIONS
--------------------------------
The following functions write strings to the active video
page. These functions are not window functions, therefore
you should use these functions when you are not using windows
created with The C Window Library unless you are careful in
using them. The advantage of using these functions instead
of the normal string writing functions found in most C
compiler libraries (i.e. printf(), puts(), etc.) is that the
output is written directly to screen memory, which results in
fast output. If the BIOS option is selected, BIOS functions
are used to write the strings. Refer to page 4 for a
discussion of direct screen writing and BIOS functions.
VideoWriteString()
------------------
This function writes a null terminated string to the active
video page. Here is the prototype:
void VideoWriteString(char *string, int row, int col)
The first argument is the string, and the second and third
arguments are the (row,col) position of the active video page
to place the string. There is no check to see if (row,col)
is out of bounds. The attribute that is used is determined
by the current video attribute at each character position on
the screen.
Example:
#include "window.h"
main()
{
int i;
WindowInitializeSystem();
for (i=1;i<=10;i++)
VideoWriteString("Hello, World",i,1);
}
There is no return value for VideoWriteString().
Page 266 The C Window Library Page 266
VideoWriteStringAttr()
----------------------
This function writes a null terminated string to the active
video page using a video attribute. Here is the prototype:
void VideoWriteStringAttr(char *string, int row, int col,
int attr)
The first argument is the string, the second and third
arguments are the (row,col) position of the active video page
to place the string, and the last argument is the video
attribute to use. There is no check to see if (row,col) is
out of bounds. The last argument is the video attribute to
use.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
main()
{
int i;
WindowInitializeSystem();
for (i=1;i<=10;i++)
VideoWriteStringAttr("Hello, World",i,1,REVERSE);
}
There is no return value for VideoWriteStringAttr().
VideoWriteAttributes()
----------------------
This function writes a string of attributes to the active
video page. Here is the prototype:
void VideoWriteAttributes(char *buffer, int row, int col,
int num)
The first argument is the buffer that contains the video
attributes. The second and third arguments are the (row,col)
position of the active video page to place the attributes,
and the last arguments is the number of attributes to write
from the buffer. There is no check to see if (row,col) is
out of bounds, or if num attributes will exceed the right
edge of the screen.
Page 267 The C Window Library Page 267
Example:
#include "window.h"
#include <string.h>
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
char buf[12];
main()
{
WindowInitializeSystem();
VideoWriteString("Hello, World",1,1);
GET_KEY();
memset(buf,REVERSE,sizeof(buf));
VideoWriteAttributes(buf,1,1,sizeof(buf));
}
The example above writes a string using the
VideoWriteString() function and then changes the attribute of
the string by setting a buffer to the REVERSE attribute and
using the VideoWriteAttributes() function with this buffer.
There is no return value for VideoWriteAttributes().
VideoWriteCenterString()
------------------------
The VideoWriteCenterString() function centers a string at a
certain row of the active video page. Here is the prototype:
void VideoWriteCenterString(char *string, int row)
The first argument is the string and the second argument is
the row to write on the active video page to write the
string. There is no check to see if row is out of bounds.
Example:
#include "window.h"
main()
{
int i;
WindowInitializeSystem();
for (i=1;i<=10;i++)
VideoWriteCenterString("Hello, World",i);
}
There is no return value for VideoWriteCenterString().
Page 268 The C Window Library Page 268
VideoWriteCenterStringAttr()
----------------------------
The VideoWriteCenterStringAttr() function centers a string at
a certain row of the active video page with a specified video
attribute. Here is the prototype:
void VideoWriteCenterStringAttr(char *string, int row,
int attr)
The first argument is the string and the second argument is
the row to write on the active video page to write the
string. The third argument is the video attribute to use.
There is no check to see if row is out of bounds.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
main()
{
int i;
WindowInitializeSystem();
for (i=1;i<=10;i++)
VideoWriteCenterStringAttr("Hello, World",i,REVERSE);
}
There is no return value for VideoWriteCenterStringAttr().
VideoWriteCharAndAttr()
-----------------------
The VideoWriteCharAndAttr() function writes a string of
character-attribute pairs to the active video page. Here is
the prototype:
void VideoWriteCharAndAttr(char *buffer, int row, int col,
int num)
The first argument is the buffer that holds the character
attribute pairs. This buffer should be in the following
form:
-----------------------------------------------
|char1 | attr1 | char2 | attr2 | char3 | attr3| ...
-----------------------------------------------
The second and third arguments are the (row,col) position of
the active video page to write the string. The last argument
Page 269 The C Window Library Page 269
is the number of character-attribute pairs to write.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
char buf[24];
main()
{
int i,j;
WindowInitializeSystem();
for (i=0,j='A'; i<24; i+=2,j++)
{
buf[i] = j;
buf[i+1] = REVERSE;
}
for (i=1;i<=10;i++)
VideoWriteCharAndAttr(buf,i,1,12);
}
The example above creates a string of character attribute
pairs and then writes this string using the
VideoWriteCharAndAttr() function.
There is no return value for VideoWriteCharAndAttr().
VideoWriteStringCC()
--------------------
This function writes a string centered around a column on the
active video page. Here is the prototype:
void VideoWriteStringCC(char *string, int row, int col)
The first argument is the string. The second argument is the
row, and the third argument is the column to center the
string around.
Example:
#include "window.h"
main()
{
int i;
WindowInitializeSystem();
VideoWriteStringCC("This",1,10);
VideoWriteStringCC("is",2,10);
VideoWriteStringCC("centered",3,10);
VideoWriteStringCC("around",4,10);
VideoWriteStringCC("column",5,10);
VideoWriteStringCC("10",6,10);
}
Page 270 The C Window Library Page 270
There is no return value for VideoWriteStringCC().
VideoWriteStringCCAttr()
------------------------
This function writes a string centered around a column on the
active video page with a specified video attribute. Here is
the prototype:
void VideoWriteStringCCAttr(char *string, int row, int col,
int attr)
The first argument is the string. The second argument is the
row. The third argument is the column to center the string
around, and the fourth argument is the attribute to use.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
main()
{
int i;
WindowInitializeSystem();
VideoWriteStringCCAttr("This",1,10,REVERSE);
VideoWriteStringCCAttr("is",2,10,REVERSE);
VideoWriteStringCCAttr("centered",3,10,REVERSE);
VideoWriteStringCCAttr("around",4,10,REVERSE);
VideoWriteStringCCAttr("column",5,10,REVERSE);
VideoWriteStringCCAttr("10",6,10,REVERSE);
}
There is no return value for VideoWriteStringCCAttr().
VideoWriteStringRJ()
--------------------
The VideoWriteStringRJ() function writes a string to the
screen that is right justified at column col. If the string
will not fit within column 1, the string is still right
justified, but excess characters to the left of column 1 are
clipped. This function writes a string column on the active
video page. Here is the prototype:
void VideoWriteStringRJ(char *string, int row, int col)
The first argument is the string. The second argument is the
row, and the third argument is the column to right justify
the string on.
Page 271 The C Window Library Page 271
Example:
#include "window.h"
main()
{
int i;
WindowInitializeSystem();
VideoWriteStringRJ("This",1,10);
VideoWriteStringRJ("is",2,10);
VideoWriteStringRJ("right",3,10);
VideoWriteStringRJ("justified",4,10);
VideoWriteStringRJ("on ",5,10);
VideoWriteStringRJ("column",6,10);
VideoWriteStringRJ("10",7,10);
}
There is no return value for VideoWriteStringRJ().
VideoWriteStringRJAttr()
------------------------
The VideoWriteStringRJAttr() function writes a string to the
screen that is right justified at column col with a specified
video attribute. If the string will not fit within column 1,
the string is still right justified, but excess characters to
the left of column 1 are clipped. This function writes a
string column on the active video page. Here is the
prototype:
void VideoWriteStringRJAttr(char *string, int row, int col,
int attr)
The first argument is the string. The second argument is the
row. The third argument is the column to right justify the
string on, and the last argument is the video attribute to
use.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
main()
{
int i;
WindowInitializeSystem();
VideoWriteStringRJAttr("This",1,10,REVERSE);
VideoWriteStringRJAttr("is",2,10,REVERSE);
VideoWriteStringRJAttr("right",3,10,REVERSE);
VideoWriteStringRJAttr("justified",4,10,REVERSE);
VideoWriteStringRJAttr("on ",5,10,REVERSE);
VideoWriteStringRJAttr("column",6,10,REVERSE);
VideoWriteStringRJAttr("10",7,10,REVERSE);
}
Page 272 The C Window Library Page 272
There is no return value for VideoWriteStringRJAttr().
VideoPrintf()
-------------
The VideoPrintf() function writes formatted strings to the
active video page. This function works exactly the same as
printf() except that output is written directly to the
screen. Here is the prototype:
void VideoPrintf(char *format [,arg1,arg2...])
The location of the output is placed at the current cursor
position. The cursor is advanced to one character beyond the
last character of output.
Example:
#include "window.h"
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
VideoPrintf("3+2 is equal to %d\n",3+2);
VideoPrintf("i is equal to %d\nj is equal to %lf\n",i,j);
}
Unlike printf(), there is no return value with VideoPrintf().
VideoPrintfAttr()
-----------------
The VideoPrintfAttr() function works the same as
VideoPrintf() except that a video attribute is specified.
Here is the prototype:
void VideoPrintfAttr(int attr, char *format [,arg1,arg2...])
The first argument is the attribute to use. The second
argument is the format string, and the other arguments are
optional arguments.
Page 273 The C Window Library Page 273
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
VideoPrintfAttr(REVERSE,"3+2 is equal to %d\n",3+2);
VideoPrintfAttr(REVERSE,
"i is equal to %d\nj is equal to %lf\n",i,j);
}
Unlike printf(), there is no return value with
VideoPrintfAttr().
Page 274 The C Window Library Page 274
READING CHARACTERS AND ATTRIBUTES FROM THE SCREEN
-------------------------------------------------
These functions read characters and/or attributes from the
active video page.
VideoReadCharacters()
---------------------
This function reads characters from the active video page
into a buffer. Here is the prototype:
void VideoReadCharacters(char *buffer, int row, int col,
int num)
The first argument is the buffer to store the characters.
The second and third arguments are the (row,col) position on
the active video page. The last argument is the number of
characters to read in. There is no check to see if the row,
col, or the num arguments are in bounds of the screen.
Example:
#include "window.h"
char buf[25];
main()
{
WindowInitializeSystem();
VideoReadCharacters(buf,1,1,25);
}
The example above reads the characters on the screen starting
at position (1,1).
There is no return value for VideoReadCharacters().
VideoReadAttributes()
---------------------
This function reads attributes from the active video page
into a buffer. Here is the prototype:
void VideoReadAttributes(char *buffer, int row, int col,
int num)
The first argument is the buffer to store the attributes.
The second and third arguments are the (row,col) position on
Page 275 The C Window Library Page 275
the active video page. The last argument is the number of
attributes to read in. There is no check to see if the row,
col, or the num arguments are in bounds of the screen.
Example:
#include "window.h"
char buf[25];
main()
{
WindowInitializeSystem();
VideoReadAttributes(buf,1,1,25);
}
The example above reads the attributes on the screen
starting at position (1,1).
There is no return value for VideoReadAttributes().
VideoReadCharAndAttr()
----------------------
This function reads character-attribute pairs from the active
video page into a buffer. Here is the prototype:
void VideoReadCharAndAttr(char *buffer, int row, int col,
int num)
The first argument is the buffer to store the
character-attribute pairs. The second and third arguments
are the (row,col) position on the active video page. The
last argument is the number of character-attribute pairs to
read in. There is no check to see if the row, col, or the
num arguments are in bounds of the screen.
Example:
#include "window.h"
char buf[26];
main()
{
WindowInitializeSystem();
VideoReadCharAndAttr(buf,1,1,13);
}
The example above reads the character-attribute pairs on the
screen starting at position (1,1).
There is no return value for VideoReadCharAndAttr().
Page 276 The C Window Library Page 276
DRAWING BOXES
-------------
The following functions draw boxes on the screen.
VideoDrawBox()
--------------
The VideoDrawBox() function draws a box on the screen. Here
is the prototype:
void VideoDrawBox(int urow, int ucol, int lrow, int lcol,
char *boxchars)
The box is defined by a rectangular region. The urow and
ucol arguments are the coordinates of the upper left hand
corner of the box. The lrow and lcol arguments are the
coordinates of the lower right hand corner of the box. The
last argument is a string of box drawing characters to use.
You can use the predefined box types in the header file
vidsys.h, or you can make your own. Refer to page 11 for
more information on box types.
There is no check to see if the coordinates are in bounds.
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white));
/* Draw two boxes */
VideoDrawBox(1,1,10,10,SINGLEBOX);
VideoDrawBox(1,11,10,21,DOUBLEBOX);
}
There is no return value for VideoDrawBox().
VideoDrawBoxAttr()
------------------
The VideoDrawBoxAttr() function draws a box on the screen
with a specified video attribute. Here is the prototype:
void VideoDrawBoxAttr(int urow, int ucol, int lrow, int lcol,
char *boxchars, int attr)
This function works the same way as the VideoDrawBox()
function. Note that the last argument is the video attribute
Page 277 The C Window Library Page 277
to use. There is no check to see if the coordinates are in
bounds.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(black,white)
main()
{
WindowInitializeSystem();
ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white));
/* Draw two boxes */
VideoDrawBoxAttr(1,1,10,10,SINGLEBOX,REVERSE);
VideoDrawBoxAttr(1,11,10,21,DOUBLEBOX,REVERSE);
}
There is no return value for VideoDrawBoxAttr().
Page 278 The C Window Library Page 278
SAVING AND RESTORING SCREEN IMAGES
----------------------------------
The following functions save rectangular regions of the
screen in a buffer, and restore rectangular portions of the
screen. These routines exist in The C Window Library so that
advanced C programmers can have general screen
saving/restoring routines handy. As always, you should be
careful in using these functions at the same time you are
using windows created with The C Window Library.
VideoSave()
-----------
The VideoSave() function saves a rectangular portion of the
screen into a structure called a VBLOCK. A pointer to this
structure is called a VBLOCKPTR. Here is the prototype:
VBLOCKPTR VideoSave(int urow, int ucol, int lrow, int lcol)
This function returns a VBLOCKPTR. The VBLOCKPTR will be
used to move or restore this saved region. The first two
arguments are the coordinates of the upper left hand corner
of the rectangle to save (urow,ucol). The last two arguments
are the coordinates of the lower right hand corner of the
rectangle (lrow,lcol). There is no check to see if the
coordinates are out of bounds. You can use this function to
save the base screen, and then use VideoRestore() to restore
the base screen on exit.
Example:
#include "window.h"
VBLOCKPTR v;
main()
{
WindowInitializeSystem();
v = VideoSave(1,1,25,80); /* Save Rectangular region */
/* Check if NULL */
if (v == (VBLOCKPTR)0)
VideoWriteString("Trouble saving video");
}
If there are no errors, VideoSave() returns a valid VBLOCKPTR.
If there are errors VideoSave() returns a null VBLOCKPTR and
sets the global integer window_error_code to the following
value:
NO_HEAP_MEM if there is not enough memory for the save buffer
of the VBLOCKPTR.
Page 279 The C Window Library Page 279
VideoMove()
-----------
The VideoMove() function moves a region saved by VideoSave()
to a different location of the screen. This location will be
the new upper left hand corner of the rectangular region that
was saved. The move is not displayed until you call
VideoRestore(), which is defined later. Here is the
prototype:
void VideoMove(VBLOCKPTR v, int row, int col)
The first argument is the VBLOCKPTR. The second and third
arguments are the new upper left hand position of the saved
area. There is NO check to see if the VBLOCKPTR exists, or
the row or column are valid.
Example:
#include "window.h"
VBLOCKPTR v;
main()
{
WindowInitializeSystem();
v = VideoSave(1,1,10,10); /* Save Rectangular region
defined by (1,1) (10,10) */
VideoMove(v,1,10);
}
There is no return value for VideoMove().
VideoRestore()
--------------
The VideoRestore() function takes a rectangular area of the
screen saved with VideoSave() and redisplays the area. Here
is the prototype:
void VideoRestore(VBLOCKPTR v)
The only argument is the VBLOCKPTR. There is no check to see
if the VBLOCKPTR is valid.
Example:
#include "window.h"
VBLOCKPTR v;
Page 280 The C Window Library Page 280
main()
{
WindowInitializeSystem();
v = VideoSave(1,1,10,10);
for (i=1;i<=10;i++)
VideoWriteString("This is the save area. "
"Press a key to restore.",i,1);
GET_KEY();
VideoRestore(v);
}
There is no return value for VideoRestore().
VideoFree()
-----------
The VideoFree() function frees a previously defined
VBLOCKPTR. Here is the prototype:
void VideoFree(VBLOCKPTR v)
The only argument is the VBLOCKPTR. There is NO check to see
if the VBLOCKPTR is valid, therefore you must be very
careful to call this function on a valid VBLOCKPTR. If not,
the heap will become corrupted.
Example:
#include "window.h"
VBLOCKPTR v;
main()
{
WindowInitializeSystem();
v = VideoSave(1,1,10,10);
for (i=1;i<=10;i++)
VideoWriteString("This is the save area. "
"Press a key to restore.",i,1);
GET_KEY();
VideoRestore(v);
VideoFree(v);
}
There is no return value for VideoFree().
Page 281 The C Window Library Page 281
CLEARING SCREENS
----------------
The following functions clears the visible video page, and
clears regions of the visible screen.
ClearScreen()
-------------
The ClearScreen() function clears the visible video page with
a specified attribute and moves the screen cursor to position
(1,1). Here is the prototype:
void ClearScreen(int attr)
The only argument is the video attribute to use.
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
/* Clear the entire screen */
ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white));
}
There is no return value for ClearScreen().
ClearRegion()
-------------
This function clears a rectangular region of the screen.
Here is the prototype:
void ClearRegion(int urow, int ucol, int lrow, int lcol,
int attr)
The first two arguments represent the coordinate of the upper
left hand coordinates of the rectangular region to clear.
The third and fourth arguments represent the coordinate of
the lower right hand corner of the rectangular region. The
last argument is the attribute to use. There is no check to
see if the coordinates are in bounds.
Page 282 The C Window Library Page 282
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
/* Clear Region defined by (1,1) as the upper right hand
corner and (10,10) as the lower right hand corner */
ClearRegion(1,1,10,10,CREATE_VIDEO_ATTRIBUTE(black,white));
}
There is no return value for ClearRegion().
Page 283 The C Window Library Page 283
SCROLLING SCREENS
-----------------
These functions scroll portions of the screen up or down.
ScrollScreenUp()
----------------
The ScrollScreenUp() function scrolls a rectangular portion
of the screen up a specified number of lines. Here is the
prototype:
void ScrollScreenUp(int numlines, int urow, int ucol,
int lrow, int lcol, int attr)
The first argument is the number of lines to scroll the
region. The second and third arguments are the (row,col)
coordinates of the upper left hand corner of the rectangular
region to scroll. The fourth and fifth arguments are the
(row,col) of the lower right hand corner of the rectangular
region. The last argument is the attribute to use for blank
lines created when the region is scrolled.
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
ScrollScreenUp(1,1,3,5,10,
CREATE_VIDEO_ATTRIBUTE(black,white));
}
There is no return value for ScrollScreenUp().
ScrollScreenDown()
------------------
The ScrollScreenDown() function scrolls a rectangular portion
of the screen down a specified number of lines. Here is the
prototype:
void ScrollScreenDown(int numlines, int urow, int ucol,
int lrow, int lcol, int attr)
The first argument is the number of lines to scroll the
region. The second and third arguments are the (row,col)
coordinates of the upper left hand corner of the rectangular
region to scroll. The fourth and fifth arguments are the
Page 284 The C Window Library Page 284
(row,col) of the lower right hand corner of the rectangular
region. The last argument is the attribute to use for blank
lines created when the region is scrolled.
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
ScrollScreenDown(1,1,3,5,10,
CREATE_VIDEO_ATTRIBUTE(black,white));
}
There is no return value for ScrollScreenDown().
Page 285 The C Window Library Page 285
CHANGING THE VIDEO MODE
-----------------------
With The C Window Library, you can change the video mode at
any time. The video mode determines the width of the screen,
and whether the screen is in text or graphics mode.
SetVideoMode()
--------------
The SetVideoMode() function changes the video mode. Here is
a prototype:
void SetVideoMode(int modenum)
The only argument is the mode number. Refer to the Video
Paging section on page 5 for more information on mode numbers
and what they display.
When the video mode is changed, the screen is cleared. This
cannot be prevented. You must redisplay any windows that
were on the screen. If the change of video mode results in a
change in screen dimensions, then you must read the following
sections on CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE
SCREEN. Even though The C Window Library does not support
graphics mode, you can change to graphics mode in The C
Window Library,
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
SetVideoMode(3); /* Change to video mode 3 */
}
There is no return value for SetVideoMode().
Page 286 The C Window Library Page 286
CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE SCREEN
-----------------------------------------------------
Changing rows
-------------
With The C Window Library, you can change the number of rows
on the video screen. However, there are some things to watch
out for when changing the number of rows, especially if you
have windows displayed on the screen. If you are not using
any window related functions, you can change the number of
displayable rows safely by doing two things:
a) Call the SetVideoRows() function to change the number of
rows.
b) Call AdjustGlobalData() to adjust the global variables
used by The C Window Library that keep track of the screen
dimensions.
If you are going to create or have created windows you must
do three things:
a) Make sure that any window defined will have valid
coordinates when the number of rows are changed. There
may be cases where a window occupies a row that exists in
one screen mode, but the row does not exist in another
screen mode. If there are windows that will have invalid
coordinates in another screen configuration, you must
resize them, remove them, or whatever it takes to resolve
the invalid coordinates.
b) Call the SetVideoRows() function.
c) Call the AdjustScreenInfo() function. This function
adjusts all global variables defined in The C Window
Library to reflect the new number of rows.
Whether there are or are not windows defined, the visible
video page MUST be page 0 before changing the number of
screen rows.
AdjustScreenInfo()
------------------
This function must be called after SetVideoRows() is called
if you are going to, or have initialized and/or displayed
windows. Here is the prototype:
int AdjustScreenInfo(int page)
Page 287 The C Window Library Page 287
The only argument is the video page to adjust to the new
screen height. Because of the new dimension of the screen,
there has to be a reshuffling of a few global arrays,
constants, variables, etc. The AdjustScreenInfo() function
does just this. If you do not call AdjustScreenInfo(), you
may see problems if you try to manipulate windows on the new
screen.
See SetVideoRows() for an example of AdjustScreenInfo().
If there are no errors, AdjustScreenInfo() returns NO_ERROR.
If there are errors, AdjustScreenInfo() returns the following
value:
NO_HEAP_MEM if there is not enough memory to allocate for the
global arrays, structures, etc.
AdjustGlobalData()
------------------
The AdjustGlobalData() function should be called after you
have changed the number of video rows using SetVideoRows()
(defined below). This resets the global variables necessary
for non-window functions to execute properly. Here is the
prototype:
void AdjustGlobalData(void)
There are no arguments and no return value for
AdjustGlobalData(). If you have called AdjustScreenInfo(),
you do not have to call AdjustGlobalData().
See below for an example of AdjustGlobalData().
SetVideoRows()
--------------
The SetVideoRows() function changes the number of video rows
on the screen. Here is a list of video adapters and there
row number capabilities:
Page 288 The C Window Library Page 288
Video Type Number of Rows
Possible
---------- --------------
CGA, MDA, Hercules 25
EGA 25, 43
MCGA 25, 50
VGA 12, 14, 21, 25, 28, 43, 50
The list above are the values SetVideoRows() uses, depending
on the adapter that The C Window Library has detected. If
your video card supports a row configuration that is not
supported by the SetVideoRows() function, consult the
'Changing columns' section and proceed as if you are changing
the number of columns.
Here is the prototype for SetVideoRows():
int SetVideoRows(int numrows, int modeflag)
The first argument is the number of screen rows. The
modeflag tells whether the video mode should be reset. If
modeflag is 0, the video mode is not reset. Any other value
for modeflag will cause a video mode reset. This reset may
or may not be necessary, so experiment with both values for
modeflag.
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white));
VideoWriteString(
"Press a key to change to a new video mode",1,1);
GET_KEY();
if (VGA_MODE_ON || MCGA_MODE_ON)
SetVideoRows(50,0);
else
if (EGA_MODE_ON)
SetVideoRows(43,0);
else
{
VideoWriteString(
"Hardware does not support changing video rows",2,1);
exit(0);
}
AdjustGlobalData();
VideoWriteString(
"Press a key again to change to 25 lines",2,1);
Page 289 The C Window Library Page 289
GET_KEY();
SetVideoRows(25,0);
AdjustGlobalData();
}
The example above uses the constants VGA_MODE_ON,
MCGA_MODE_ON, and EGA_MODE_ON. These constants are discussed
in the VIDEO MACROS section.
Here is another example, but now we have a window on the
screen.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Press a key to change rows",1,1);
GET_KEY();
if (VGA_MODE_ON || MCGA_MODE_ON)
SetVideoRows(50,0);
else
if (EGA_MODE_ON)
SetVideoRows(43,0);
else
{
WindowWriteString(w,"Cannot change rows",1,1);
exit(0);
}
/* Adjust the screen information */
AdjustScreenInfo(0);
/* OK to adjust to new height */
WindowResizeHeight(w,40,ANCHORTOP);
WindowWriteString(w,"Now press a key to change back",2,1);
GET_KEY();
/* First we must resize window */
WindowResizeHeight(w,10,ANCHORTOP);
SetVideoRows(25,0);
Page 290 The C Window Library Page 290
AdjustScreenInfo(0);
}
Note the use of AdjustScreenInfo() after a reset is made.
If there are no errors, SetVideoRows() returns no errors.
If there are errors SetVideoRows() returns the following
value:
INVALID_ROWS if the number of rows is not supported for the
detected monitor type.
Changing columns
----------------
The number of columns can be changed, but there are two
things to watch out for. First, to change from 40 column
mode to 80 column mode or vice-versa, is a matter of changing
the video mode. Changing the video mode from 40 to 80 column
mode or from 80 to 40 requires a BIOS function that is
present on all systems that support 40 column mode.
40 column and 80 column modes
-----------------------------
To change to 40 column mode do the following:
SetVideoMode(0); /* this changes to 40 column
black and white mode */
or
SetVideoMode(1); /* this changes to 40 column color mode */
The example above only works if you have a CGA, EGA, MCGA, or
VGA card.
To change to 80 column mode do the following:
SetVideoMode(2); /* this changes to Black and White
80 column mode */
or
SetVideoMode(3); /* use this for color 80 column mode */
or
Page 291 The C Window Library Page 291
SetVideoMode(7); /* use this for mono cards */
SetVideoMode(7) works for all adapters, while SetVideoMode(2)
and SetVideoMode(3) works only for CGA, EGA, MCGA, or VGA
cards.
Modes higher than 80 columns
----------------------------
There are video systems that support video modes greater than
80 columns. The problem is that for each different brand of
video adapter, there is a unique way of changing to a higher
column mode. Most of these adapters support an additional
BIOS function that must be called to change to any screen
column mode higher than 80. Therefore, it is up to you (the
programmer) to find out how to change the video system from
80 columns to a higher column mode. Once you are familiar
with how to do this, changing the number of columns is almost
the same as changing the number of rows.
If you are using any window related functions, you can change
the number of displayable columns safely by doing three
things:
a) Call the appropriate routine to change the number of
columns. If this is a call to SetVideoMode(), the screen
will be cleared.
b) Call AdjustScreenInfo() to adjust the global variables
used by The C Window Library that keep track of the screen
dimensions.
c) Readjust and/or redraw any windows on the screen. Make
sure that all windows fit on the screen, whether they are
hidden or not.
If you are not using any windows in your application, replace
the call to AdjustScreenInfo() in step b) with a call to
AdjustGlobalData().
This example works for the ATI VGA card. This changes the
mode to 132 columns:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
Page 292 The C Window Library Page 292
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Press a key to change columns",1,1);
GET_KEY();
/* Set Video Mode to 132 columns x 25 rows
(Works for ATI VGA card) */
SetVideoMode(0x23);
/* Adjust the screen information and redisplay window */
AdjustScreenInfo(0);
WindowDisplay(w,1,NOEFFECT);
/* OK to adjust to new height */
WindowResizeWidth(w,100,ANCHORLEFT);
WindowWriteString(w,"Now press a key to change back",2,1);
GET_KEY();
/* First we must resize window */
WindowResizeWidth(w,30,ANCHORLEFT);
/* Set back to 80 column mode */
SetVideoMode(3);
AdjustScreenInfo(0);
WindowDisplay(w,1,NOEFFECT);
}
Page 293 The C Window Library Page 293
CURSOR MANIPULATION
-------------------
The functions defined in this section manipulate the cursor.
The following functions can be called without calling
WindowInitializeSystem().
MoveCursor()
------------
This function moves the cursor to a different location. Here
is the prototype:
void MoveCursor(int row, int col, int page)
The first two arguments are the row and column positions of
where to move the cursor. The last argument is the video
page of the cursor you want to move.
Example:
#include "window.h"
main()
{
MoveCursor(1,5,0); /* Move cursor to row 1 column 5
on video page 0 */
}
There is no return value for MoveCursor().
ChangeCursor()
--------------
The ChangeCursor() function changes the shape of the cursor.
The shape of the cursor is determined by its starting and
ending scan lines. Here is a prototype:
void ChangeCursor(unsigned startline, unsigned endline)
The first argument is the starting scan line and the second
argument is the ending scan line. For monochrome systems,
there are 12 scan lines numbered 0 thru 11, while on color
systems there are 8 scan lines numbered 0 thru 7. The
starting scan line is the top line of the cursor, and the
ending scan line is the last line of the cursor. There is no
check to see if the starting scan line and the ending scan
lines are valid.
Page 294 The C Window Library Page 294
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
ChangeCursor(6,7); /* This is an underline cursor */
GET_KEY();
ChangeCursor(0,7); /* This is a thick cursor */
}
There is no return for ChangeCursor().
GetCursorShape()
----------------
This function returns the shape of the cursor in scan lines.
Here is the prototype:
void GetCursorShape(unsigned *startline, unsigned *endline)
When this function returns, the staring scan line is placed
in the integer pointed to by scanline, and the ending scan
line is placed in the integer pointed to by endline.
Example:
#include "window.h"
main()
{
int start, end;
WindowInitializeSystem();
GetCursorShape(&start, &end);
VideoPrintf("\nThe starting scan line is %d\n"
"The ending scan line is %d", start,end);
}
There is no return value for GetCursorShape().
GetCursorPosition()
-------------------
This function gets the current cursor position. Here is the
prototype:
void GetCursorPosition(int *row, int *col, int page)
The first argument is a pointer to an integer that will be
Page 295 The C Window Library Page 295
set to the current row. The second argument is a pointer to
an integer that will be set to the current column. The last
argument is the video page of the cursor.
Example:
#include "window.h"
main()
{
int row,col;
MoveCursor(10,15);
GetCursorPosition(&row,&col,0);
WindowInitializeSystem();
VideoPrintf("\nThe row of the cursor is %d\n"
"The column is %d", row,col);
}
There is no return value for GetCursorPosition().
The following functions serve as shortcuts in changing the
cursor shape.
HideCursor()
------------
Hides the cursor on the screen. Here is the prototype:
void HideCursor(void)
BlockCursor()
-------------
Displays the cursor as a thick block.
void BlockCursor(void)
ThinCursor()
------------
Displays the cursor as an underline cursor.
void ThinCursor(void)
Page 296 The C Window Library Page 296
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
MoveCursor(1,1,0);
VideoWriterString("Press a key to hide the cursor",1,1);
GET_KEY();
HideCursor();
VideoWriterString(
"Press a key to change cursor to a block",2,1);
GET_KEY();
BlockCursor();
VideoWriterString(
"Press a key to change cursor to a thin cursor",3,1);
GET_KEY();
ThinCursor();
}
There are no return values for HideCursor(), BlockCursor(),
or ThinCursor().
Page 297 The C Window Library Page 297
GETTING VIDEO INFORMATION
-------------------------
You can get information about the video configuration by
calling the GetVideoBiosInfo() function.
VIDEO_CONFIG structure
----------------------
To get information about the video configuration, you must
pass a pointer to a VIDEO_CONFIG structure. This structure
is defined as follows:
typedef struct
{
unsigned int video_mode; /* Current video mode */
unsigned int cursor_startline; /* Starting scan line of
cursor */
unsigned int cursor_endline; /* Ending scan line of
cursor */
unsigned int cursor_row; /* Screen row of cursor */
unsigned int cursor_col; /* Column of cursor */
unsigned int video_page; /* Current visible video
page */
unsigned int video_pagesize; /* Size in bytes of the
video page */
unsigned int video_rows; /* Number of displayable
rows */
unsigned int video_cols; /* Number of displayable
columns * /
unsigned int char_height; /* Height (in scan lines)
of a character */
unsigned int crt_port_address; /* Address of CRT status
port */
unsigned int crt_mode_setting; /* Current CRT Mode
Setting */
unsigned int crt_color_setting; /* Current CRT color
settings */
} VIDEO_CONFIG;
GetVideoBiosInfo()
------------------
This function returns information about the current video
configuration. Here is the prototype:
void GetVideoBiosInfo(VIDEO_CONFIG *v)
The only argument is a pointer to a VIDEO_CONFIG structure.
This structure is filled in with the appropriate values.
Page 298 The C Window Library Page 298
Example:
#include "window.h"
VIDEO_CONFIG v;
main()
{
WindowInitializeSystem();
/* Get video information */
ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white));
GetVideoBiosInfo(&v);
VideoPrintf("The video mode is %d\n"
"The starting scan line of the cursor is %d\n"
"The ending scan line of the cursor is %d \n"
"The row of the cursor is %d \n"
"The column of the cursor is %d\n"
"The video page is %d\n"
"The size of the video page is %d\n"
"The number of rows is %d\n"
"The number of columns is %d\n"
"The height of the characters is %d\n",
v.video_mode, v.cursor_startline,
v.cursor_endline,
v.cursor_row,v.cursor_col,
v.video_page, v.video_pagesize,
v.video_rows, v.video_cols,
v.char_height);
}
There is no return value for GetVideoBiosInfo().
Page 299 The C Window Library Page 299
TIMED DELAYS
------------
One of the problems that has been addressed in The C Window
Library is the lack of a delay() function in most C compiler
packages. The delay() function delays program execution for
a certain number of milliseconds. Borland's Turbo C compiler
is one of the few that has a delay() function. The other
compilers may have a sleep() function, but usually these
functions do not have millisecond accuracy.
One of the problems was to write a delay() function that
would work for all the major C compilers, work with
millisecond accuracy, work for any speed PC, and last but not
least, without using floating point arithmetic. This
function was written in assembly language for accuracy. The
use of the delay() is used extensively in displaying and
hiding windows with certain special effects.
delay()
-------
The delay() function delays the program for a certain number
of milliseconds. Here is the prototype:
void delay(unsigned millisecs)
The only argument is the number of milliseconds to delay. If
you are using the Turbo C version of The C Window Library,
this function is already included in the Turbo C library.
However, if you are using another compiler you now have a
delay() function!
Example:
main()
{
WindowInitializeSystem();
delay(50); /* Delay for 50 milliseconds */
}
You must call WindowInitializeSystem() before using delay().
There is no return value for delay().
Page 300 The C Window Library Page 300
SOUND FUNCTIONS
---------------
The C Window Library also supports sound functions for
compilers that are lacking these functions.
sound() and nosound()
---------------------
The sound() function sounds a tone with a specified frequency
in Hertz (cycles per second). Here is a prototype:
void sound(unsigned frequency)
The nosound() function turns off the tone generated by the
sound() function.
Example:
#include "window.h"
main()
{
unsigned i;
WindowInitializeSystem();
for (i=100;i<=1000;i++)
sound(i);
for(i=1000;i>=100;i--)
sound(i);
nosound();
}
Note for Turbo users:
You should include "dos.h" in your files that contain sound()
and nosound(). All other compilers should include
"window.h".
Note for Power C users: If you are using the Power C
compiler, you must include "window.h" or any file that
includes window.h after bios.h. This is to ensure that the
linker does not get confused with the Power C function
called sound(), which works differently than the sound()
function defined above.
MakeSound()
-----------
The MakeSound() function sounds a tone for a duration of
time. Here is the prototype:
Page 301 The C Window Library Page 301
void MakeSound(unsigned freq, unsigned millisec)
where freq, is the frequency of the tone (in Hertz) and
millisec is the number of milliseconds to sound the tone.
Example:
--------
#include "window.h"
main()
{
WindowInitializeSystem();
/* Produce a 440 Hertz tone for 3 seconds */
MakeSound(440,3000);
}
There is no error return for this function.
Page 302 The C Window Library Page 302
ERROR HANDLING
--------------
Whenever an error has occurred in The C Window Library, a
user defined error function can be called.
The window_error_func function pointer
--------------------------------------
The window_error_func function pointer can point to an error
function that is performed whenever there is an error
encountered in one of The C Window Library functions. If the
global variable check_existence_flag is set to 1 and there is
an error, The C Window Library will automatically call
window_error_func. Here is the prototype:
void (*window_error_func)(int errcode, char *sourcefile,
int sourceline, char *funcname)
The errcode is one of the defined error codes included in The
C Window Library. Refer to page 6 of the main documentation
for more information of the error codes and their
definitions. The second argument is the name of the file
where the error occurred. Only users with the source code to
The C Window Library will have access to this file. The
third argument is the offending line in the source file of
where the error occurred. The last argument is the name of
the function of where the error occurred.
By default window_error_func points to a void null function
(VOIDNULLFN), therefore no error function is called.
Here is an example of how to implement automatic error
checking:
#include "window.h"
#define WHITEONRED CREATE_VIDEO_ATTRIBUTE(red,white)
void custom_error_func(int, char *, int, char *);
WPOINTER w, error_window;
void initialize_error();
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
window_error_func = custom_error_func; /* Assign error
function */
initialize_error();
WindowOpen(w); /* will be flagged for an error */
}
void initialize_error() /* Initialize error window and
error handler */
Page 303 The C Window Library Page 303
{
error_window =
WindowInitialize(BORDER,1,1,60,5,WHITEONRED,
WHITEONRED,SINGLEBOX);
WindowOpen(error_window);
}
void custom_error_func(int errcode, char *sourcefile,
int sourceline, char *funcname)
{
int ch;
MakeSound(100,500); /* Produce an error beep */
if (errcode == NO_HEAP_MEM) /* Always check for the heap
memory error separately */
{
VideoWriteString("You have ran out of Heap Memory",1,1);
VideoWriteString(
"Press 'Q' to quit program, Any other key to Continue...",
2,1);
}
else /* Display error window */
{
WindowClear(error_window);
WindowDisplay(error_window,1,EXPLODE);
WindowPrintf(error_window,
"Error Code: %d\nSource File: %s\nSource Line %d\n"
"Error Occurred in %s",
errcode,sourcefile,sourceline,funcname);
WindowWriteString(error_window,
"Press 'Q' to quit program, Any other key to Continue...",
5,1);
}
ch = GET_KEY();
if (ch == 'Q' || ch == 'q')
exit(0);
else
if (errcode != NO_HEAP_MEM)
WindowHide(error_window,CONTRACT);
}
The above example initializes an error window and sets the
window_error_func function pointer to point to the function
custom_error_func(). Whenever an error occurs in The C
Window Library, custom_error_func() will be called.
Please note the check to see if the NO_HEAP_MEM error has
occurred. It is important that you check for this error
condition separately. The reason for this is that if there
is not enough heap memory, you may inadvertently call a
function in your error handler that calls on malloc() or any
Page 304 The C Window Library Page 304
of the other memory allocation related functions. This will
either freeze your system, or more peculiarly, cause your
error handler to be called in an infinite loop because of the
repeated failing calls to malloc() or its related functions.
In the latter case, you will run out of stack space.
If you want to unassign the window_error_code function
pointer, use the following line in your code:
window_error_func = VOIDNULLFN;
Page 305 The C Window Library Page 305
USING A MOUSE WITH THE C WINDOW LIBRARY
---------------------------------------
With The C Window Library, you can create applications that
use a Microsoft compatible mouse to select from popup,
pulldown, and bar menus as well as getting mouse presses.
Using the mouse for menus will be discussed in this section,
while getting and testing for button presses will be
discussed in the KEYBOARD MACROS section below.
Installing the Mouse Library
----------------------------
Before using the mouse library, make sure that you read the
README file concerning installing the mouse library.
Include files
-------------
The only include file needed is cwlmouse.h. This file also
includes window.h.
Initializing the Mouse with MouseInitializeSystem()
---------------------------------------------------
Before you can use a mouse, you must initialize it by calling
MouseInitializeSystem(). This function tests for a Microsoft
compatible mouse and returns a value denoting whether a mouse
is found. Here is the prototype:
int MouseInitializeSystem(int intype, int *button, int hpos,
int vpos)
The first argument informs MouseInitializeSystem() to whether
you just want to test to see if a mouse is installed and not
to activate the mouse, or to not only test for the mouse, but
to activate it. If the first argument is MOUSE_TEST,
MouseInitializeSystem() will just return an integer denoting
whether a mouse is found. If the first argument is
MOUSE_FULL_INSTALL, not only is a status returned, but the
mouse will be activated.
The second argument is a pointer to an integer that will
contain the number of buttons that the mouse has. This
number will usually be 2 or 3.
The third and fourth arguments are the screen coordinates of
where to place the mouse cursor on the screen. The third
argument is the row, and the fourth argument is the column to
place the mouse cursor.
MouseInitializeSystem() returns NOMOUSE if a mouse is not
installed, or MOUSEFOUND if a mouse is installed.
Page 306 The C Window Library Page 306
MouseInitializeSystem() must be called after calling
WindowInitializeSystem() for it to work properly.
Turning off the mouse with MouseRestoreSystem()
-----------------------------------------------
Before terminating a program that has called
MouseInitializeSystem() you should call MouseRestoreSystem().
If you do not call MouseRestoreSystem(), the mouse will still
be 'alive', even though the application has terminated. Here
is the prototype:
int MouseRestoreSystem(void)
If the mouse was not initialized previously with
MouseInitializeSystem(), MouseRestoreSystem() returns
NOMOUSE, otherwise the return value is NO_ERROR.
Example:
#include "cwlmouse.h"
main()
{
/* initialize mouse */
MouseInitializeSystem();
/* ... */
/* turn off mouse */
MouseRestoreSystem();
}
If you want to turn the mouse back on after calling
MouseRestoreSystem(), you must call MouseInitializeSystem()
again.
Example:
#include "cwlmouse.h"
main()
{
int button;
int ismouse;
WindowInitializeSystem();
ismouse = (MouseInitializeSystem(MOUSE_FULL_INSTALL,
&button,1,1) == MOUSEFOUND));
MoveCursor(1,1,0);
if (ismouse)
Page 307 The C Window Library Page 307
VideoPrintf(
"Mouse was found. Number of buttons is %d\n",button);
else
VideoPrintf("Mouse not found");
}
Using a mouse with popup menus
------------------------------
Once the mouse is initialized, you can use the mouse to make
selections with popup menus.
To move the highlight bar with the mouse, position the mouse
cursor over any menu entry in the window, and hold the left
mouse button down. If the mouse is moved while holding the
left button down, the highlight is moved along with the mouse
cursor. A selection is made by releasing the left mouse
button while the mouse cursor is on an active menu entry.
You can also scroll through the menu entries by placing the
mouse on either a down arrow or up arrow symbols on the popup
menu window, and then holding the left mouse button down. By
default, the symbols appear at the bottom border of the
window. If the popup window is borderless, the
POPUPMOUSESCROLL option is ignored.
To activate the mouse so that it can be used for popup menus,
you must set the popup option POPUPMOUSE on. If you also
want to use the scroll through option described above,
POPUPMOUSESCROLL should also be turned on.
Example:
#include "menu.h"
#include "cwlmouse.h"
int menu_func();
POPUP_MENU_ENTRY menu_items[] = {
" Load F3",1,'L',F3,menu_func,
" Pick Alt-F3",2,'P',ALTF3,menu_func,
" New" ,3,'N',0,menu_func,
" Save F2",4,'S',F2,menu_func,
" Write to ",5,'W',0,menu_func,
" Directory ",6,'D',0,menu_func,
" Change Dir" ,7,'C',0,menu_func,
" OS shell" ,8,'O',0,menu_func,
" Quit Alt-X" ,9,'Q',ALTX,menu_func,
CWL_NULL,0};
unsigned int menu_colors[5];
POPUP_MENU_PTR p;
Page 308 The C Window Library Page 308
main()
{
int b;
WindowInitializeSystem();
WindowSaveInitial(0);
/* Remember to save the initial screen */
MouseInitiailizeSystem(MOUSE_FULL_INSTALL,&b,1,1);
/* define colors */
menu_colors[ENTRYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[BORDERCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[HOTKEYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[HIGHLIGHTCOLOR] =
CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[UNAVAILCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a POPUP_MENU_PTR */
p = PopupCreateMenu(menu_items,menu_colors, 1,1,6,
POPUPSTATIC | POPUPMOUSE | POPUPMOUSESCROLL,
WNULLFN,VWNULLFN);
PopupSelectMenu(p, /* POPUP_MENU_PTR */
1, /* rank of popup window */
1 /* menu entry to start on */
);
MouseRestoreSystem();
}
int menu_func(POPUP_MENU_PTR p, unsigned which)
{
WPOINTER w;
w = WindowInitialize(BORDER,15,15,40,4,
CREATE_VIDEO_ATTRIBUTE(black,white),
CREATE_VIDEO_ATTRIBUTE(black,white),
SINGLEBOX);
WindowOpen(w);
WindowClear(w);
WindowPrintf(w,"You have selected %s",
POPUP_ENTRY_STRING(p,which));
WindowWriteCenterString(w,"Press a key to continue",3);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowFree(w,NOEFFECT);
if (which == 9)
return POPUP_EXIT;
else
return POPUP_CONTINUE;
}
Page 309 The C Window Library Page 309
The above example uses the popup menu option POPUPMOUSE and
POPUPMOUSESCROLL options in the PopupCreateMenu() function.
Also note the call to MouseInitializeSystem() to initialize
the mouse system. You must use the constant
MOUSE_FULL_INSTALL in the MouseInitializeSystem() function to
make sure that the POPUPMOUSE and the POPUPMOUSESCROLL
options will take effect. If a mouse does not exist, or the
mouse is not activated, POPUPMOUSE and POPUPMOUSESCROLL will
be ignored. Also note that the include file cwlmouse.h was
included. These are the only changes needed for mouse
support for the popup menus.
Popup Menu's pre-function for mouse
-----------------------------------
When the POPUPMOUSESCROLL option is used for popup menus, the
menu can be scrolled automatically by placing the mouse on
either the up or down scroll characters on the popup window,
and pressing the left mouse button.
The normal pre-function for the popup menu, namely the
function pointed to by global_popup_prefunc, is disabled if
you use the mouse to scroll through the entries in the manner
described above. If you want to perform a function when the
menu bar is moved automatically from choice to choice, you
should use the popup_mouse_move_func function pointer. Here
is the prototype:
void (*popup_mouse_move_func)(POPUP_MENU_PTR p,
unsigned current)
p is the current popup menu, and current is the current
selection that the highlight bar is on.
Note the difference in the second argument. The
global_popup_prefunc function pointer has a pointer to an
integer as the second argument, while the
popup_mouse_move_func has an integer as the second argument.
Also note that the popup_mouse_move_func returns nothing,
while the global_popup_prefunc returns a value back to the
menu manager.
If you use the mouse the 'normal' way (pointing the mouse to
the actual menu entry and moving the mouse up or down while
holding the left mouse button down), the normal pre-function
is not disabled.
The reason for having the popup_mouse_move_func function
pointer is that there may be a description displayed for each
menu entry, where the displaying of the menu entry is done by
the function pointed to by global_popup_prefunc. Here is a
small example:
Page 310 The C Window Library Page 310
#include "menu.h"
#include "cwlmouse.h"
int display_choice();
void do_display_choice();
POPUP_MENU_PTR p;
/* other initializations */
main()
{
WindowInitializeSystem();
WindowSaveInitial();
MouseInitializeSystem(MOUSE_FULL_INSTALL,&b,1,1);
p = PopupCreateMenu(/* arguments */);
PopupSetOptions(p,POPUPMOUSE|POPUPMOUSESCROLL,1);
global_popup_prefunc = display_choice;
popup_move_mouse_func = do_display_choice;
/*
...
*/
}
display_choice(POPUP_MENU_PTR p, int *choice)
{
/* display info for entry in a window */
return POPUP_CONTINUE;
}
void do_display_choice(POPUP_MENU_PTR p, int choice)
{
display_choice(p,&choice);
}
Using a mouse with bar menus
----------------------------
To move the highlight bar with the mouse, position the mouse
cursor over any menu entry in the window, and hold the left
mouse button down. If the mouse is moved while holding the
left button down, the highlight is moved along with the mouse
cursor. A selection is made by releasing the left mouse
button while the mouse cursor is on an active menu entry.
To activate the mouse so that it can be used for bar menus,
you must set the bar menu option BARMOUSE on.
Page 311 The C Window Library Page 311
Example:
#include "menu.h"
#include "cwlmouse.h"
int menu_func();
BAR_MENU_ENTRY bar_items[] = {
"File",1,4,'F',ALTF,menu_func,
"Edit",1,10,'E',0,menu_func,
"Run",1,17,'R',0,menu_func,
"Compile",1,23,'C',0,menu_func,
"Project",1,33,'P',0,menu_func,
"Options", 1,43,'O',0,menu_func,
"Debug",1,53,'D',0,menu_func,
"Break/watch",1,61,'B',0,menu_func,
CWL_NULL};
unsigned int menu_colors[5];
BAR_MENU_PTR b;
main()
{
int b;
WindowInitializeSystem();
WindowSaveInitial(0);
MouseInitializeSystem(MOUSE_FULL_INSTALL,&b,1,1);
menu_colors[ENTRYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[BORDERCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[HOTKEYCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[HIGHLIGHTCOLOR] =
CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[UNAVAILCOLOR] =
CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a BAR_MENU_PTR */
b = BarCreateMenu(bar_items,menu_colors, 1,1,
BARSTATIC | BARWRAP | BARMOUSE,WNULLFN);
BarSelectMenu(b,1,1);
MouseRestoreSystem();
}
Page 312 The C Window Library Page 312
int menu_func(BAR_MENU_PTR b, unsigned which)
{
WPOINTER w;
w = WindowInitialize(BORDER,15,15,40,4,
CREATE_VIDEO_ATTRIBUTE(black,white),
CREATE_VIDEO_ATTRIBUTE(black,white),
SINGLEBOX);
WindowOpen(w);
WindowPrintf(w,"You have selected %s",
BAR_ENTRY_STRING(b,which));
WindowWriteCenterString(w,"Press a key to continue",3);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowFree(w,NOEFFECT);
if (which == 9)
return BAR_EXIT;
else return BAR_CONTINUE;
}
The above example uses the bar menu option BARMOUSE option in
the BarCreateMenu() function. Also note the call to
MouseInitializeSystem() to initialize the mouse system. You
must use the constant MOUSE_FULL_INSTALL in the
MouseInitializeSystem() function to make sure that the
BARMOUSE option will take effect. If a mouse does not exist,
or the mouse is not activated, BARMOUSE will be ignored.
Also note that the include file cwlmouse.h was included.
These are the only changes needed for mouse support for the
bar menus.
Using a mouse with pulldown menus
---------------------------------
If the menu options for the mouse are turned on for all popup
menus and the bar menu, and these menus are used as part of a
pulldown menu system, the mouse behaves exactly the same
except for the following differences:
a) Holding the left mouse button down and positioning the
mouse cursor over a bar menu entry will bring up the
popup menu that is associated with the bar entry. If
there is no popup menu defined for a particular bar
entry, releasing the mouse button will invoke the
entry's function.
b) Releasing the mouse button when it is positioned over a
bar entry, and the bar entry has a popup associated with
it, does nothing. A general rule is that a menu
function is only executed when the highlight bar is
positioned on a menu entry that has a function
associated with it.
Page 313 The C Window Library Page 313
Changing the mouse defaults
---------------------------
By default, the left mouse button is held down when moving
the highlight bar. If you prefer a different button to be
used to move the highlight bar, you can change the button by
changing the following global variables:
int popmenu_button_press - holds the current button to be
used to move the highlight bar in popup menus.
int barmenu_button_press - holds the current button to be
used to move the highlight bar in bar menus.
The following constants can be assigned to these two global
variables:
Constant Definition
-------- ----------
MOUSELEFT_PRESS Left button.
MOUSERIGHT_PRESS Right button.
MOUSEMIDDLE_PRESS Middle button.
By default, popmenu_button_press and barmenu_button_press are
assigned MOUSELEFT_PRESS. Here is an example of changing
these variables:
#include "cwlmouse.h"
#include "menu.h"
main()
{
...
MouseInitializeSystem( /* arguments */ );
/* change mouse menu buttons */
popmenu_button_press = MOUSERIGHT_PRESS;
barmenu_button_press = MOUSERIGHT_PRESS;
...
}
The popmenu_button_press and barmenu_button_press variables
are assigned their default values when
MouseInitializeSystem() is called. If you want to change
these variables, make sure that the change is made after
calling MouseInitializeSystem().
Page 314 The C Window Library Page 314
WINDOW AND VIRTUAL WINDOW MACROS
--------------------------------
Note : These macros should be used after making a call to
WindowInitializeSystem() or else unpredictable values will be
returned.
The following macros are defined in the window.h file.
The window w is NOT CHECKED for validity.
ISBORDER(w) - Returns 1 if window has a border, 0
otherwise.
ISWRAP(w) - Returns 1 if window wrap is on, 0
otherwise.
ISOPEN(w) - Returns 1 if window has been opened for
read/write, 0 otherwise.
ISVISIBLE(w) - Returns 1 if window is visible, 0
otherwise.
ISVIEWPORT(w) - Returns 1 if window is a viewport, 0
otherwise.
ISWINDOW(vw) - Returns 1 if virtual window has any
viewports, 0 otherwise.
ISBUFSAVE(w) - Returns 1 if text buffer for window was
successfully, allocated, 0 otherwise.
ISSEETHRU(w) - Returns 1 if window is in see-thru mode, 0
otherwise.
ISFROZEN(w) - Returns 1 if window is frozen from doing
screen updates when the virtual window has
changed, 0 otherwise.
ISSHADOW(w) - Returns 1 if the window has a shadow, 0
otherwise.
ISSHADOWTRANS(w) - Returns 1 if the shadow is transparent, 0
otherwise.
SHADOW_POS(w) - Returns the position of the shadow as an
integer. The valid positions are as
follows:
Shadow Position Return Value
--------------- ------------
SHADOWUPLEFT 1
SHADOWUPRIGHT 2
SHADOWLOWLEFT 3
Page 315 The C Window Library Page 315
SHADOWLOWRIGHT 4
If there is no shadow, a 0 is returned.
SHADOW_CHAR(w) - Returns the current character used to draw
the window's shadow. Return value is
undefined if the window has no shadow.
SHADOW_ATTR(w) - Returns the current video attribute used to
draw the window's shadow. Return value is
undefined if the window has no shadow
SHADOW_WIDTH(w) - Returns the width of the window's shadow.
Return value is undefined if the window has
no shadow.
SHADOW_HEIGHT(w) - Returns the height of the window's shadow.
Return value is undefined if the window
has no shadow.
VIRTUAL_ATTRIBUTE_ON(vw) - Returns 1 if the virtual window vw
is attributed, 0 otherwise.
VIRTUAL_WINDOW_EXIST(vw) - Returns 1 if virtual window was
initialized, 0 otherwise.
VIRTUAL_HEIGHT(vw) - Returns the number of rows in a virtual
window vw.
VIRTUAL_WIDTH(vw) - Returns the number of columns in a
virtual window.
VIRTUAL_WINDOW(w) - Returns the virtual window that the
viewport w is currently viewing.
VIEWPORT_ROW(w) - Returns the upper left row of where the
viewport w is positioned on the virtual
window.
VIEWPORT_COLUMN(w) - Returns the upper left column of where
the viewport w is positioned on the
virtual window.
VIRTUAL_COORD_IN_VIEWPORT(w,row,col) - Returns 1 if the
virtual window coordinates (row,col)
are inside the viewport w, 0
otherwise. The virtual window must
have w as a viewport.
WINDOW_BORDER_CHARS(w) - Returns the current border of a
window as a string.
Page 316 The C Window Library Page 316
WINDOW_BORDER_COLOR(w) - Returns the border color of the
window w.
WINDOW_COLUMN(w) - Returns the absolute column of the upper
left hand corner of the window.
WINDOW_EXIST(w) - Returns 1 if window was initialized, 0
otherwise.
WINDOW_HEIGHT(w) - Returns the height of the text area of the
window w.
WINDOW_PAGENUM(w) - Returns the video page of where the
window will be displayed.
WINDOW_RANK(w) - Returns the rank of the window w.
WINDOW_ROW(w) - Returns the absolute row coordinate of the
upper left hand corner of the window w.
Page 317 The C Window Library Page 317
MENU MACROS
-----------
The following macros are defined in the header file menu.h.
Popup Menu Macros
-----------------
POPUP_CONFIRM_ON(p) - Returns 1 if the POPUP_MENU_PTR p has
the confirmation for hotkey selections
on, 0 otherwise.
POPUP_DISPLAY_ON(p) - Returns 1 if the POPUP_MENU_PTR p's
window is to be displayed regardless if
the menu manager has returned to the
calling function, 0 otherwise.
POPUP_ENHANCED_ON(p) - Returns 1 if the popup menu will
recognize enhanced keys, 0 otherwise.
POPUP_ENTRY_STRING(p,entry) - Returns the entry string of
POPUP_MENU_ENTRY entry.
POPUP_EXPLODE(p) - Returns the special effect constant of
the POPUP_MENU_PTR p. This special
effect is used to hide, close, and open
the popup menu's window.
POPUP_MOUSE_ON(p) - Returns 1 if a mouse can be used to
make selections, 0 otherwise.
POPUP_MOUSE_SCROLL_ON(p) - Returns 1 if a mouse can be used
to scroll through the entries if
the entries cannot fit in the
popup window, 0 otherwise.
POPUP_NUMBER_OF_ENTRIES(p) - Returns the total number of
entries defined in the
POPUP_MENU_PTR p.
POPUP_OVERRIDE_ON(p) - Returns 1 if POPUP_MENU_PTR p will
have unavailable options processed, 0
otherwise.
POPUP_PULLDOWN_ON(p) - Returns 1 if the POPUP_MENU_PTR p is
incorporated in a pulldown menu
system, 0 otherwise.
POPUP_SCROLL_UP_CHAR(p) - This is the scroll up character
that is displayed if the
POPUPMOUSESCROLL option is on for
the popup menu p. The default
character is the up arrow.
Page 318 The C Window Library Page 318
POPUP_SCROLL_DOWN_CHAR(p) - This is the scroll down character
that is displayed if the
POPUPMOUSESCROLL option is on for
the popup menu p. The default
character is the down arrow.
POPUP_SCROLL_UP_ATTR(p) - This is the color attribute for the
scroll up character that is
displayed if the POPUPMOUSESCROLL
option is on for the popup menu p.
The default character is the
attribute of the popup window.
POPUP_SCROLL_DOWN_ATTR(p) - This is the color attribute for
the scroll down character that is
displayed if the POPUPMOUSESCROLL
option is on for the popup menu
p. The default character is the
attribute of the popup window.
POPUP_SCROLL_UP_ROW(p) - This is the row that the scroll up
character is displayed in the popup
window. The default is the bottom
border of the window
POPUP_SCROLL_UP_COLUMN(p) - This is the column that the
scroll up character is displayed
in the popup window. The default
is column 1.
POPUP_SCROLL_DOWN_ROW(p) - This is the row that the scroll
down character is displayed in the
popup window. The default is the
bottom border of the window
POPUP_SCROLL_DOWN_COLUMN(p) - This is the column that the
scroll down character is
displayed in the popup window.
The default is column 1.
POPUP_STATIC_ON(p) - Returns 1 if the POPUP_MENU_PTR p will
remain on the screen when an entry is
selected, 0 otherwise.
POPUP_STRING_IN_WINDOW(p,entry) - Returns 1 if the
POPUP_MENU_PTR p has entry number entry
displayed in the popup menu's window, 0
otherwise. This macro is useful if you
have a scrolling popup menu and want to
know if a particular entry is displayed in
the window.
POPUP_VIRTUAL_WINDOW(p) - Returns the VWPOINTER of the popup
menu.
Page 319 The C Window Library Page 319
POPUP_WINDOW(p) - Returns the WPOINTER of the popup menu.
POPUP_WRAP_ON(p) - Returns 1 if the highlight wrap of
POPUP_MENU_PTR p is on, otherwise 0.
Bar Menu Macros
---------------
BAR_CONFIRM_ON(b) - Returns 1 if the BAR_MENU_PTR b has the
confirmation for hotkey selections on, 0
otherwise.
BAR_DISPLAY_ON(b) - Returns 1 if the BAR_MENU_PTR b's window
is to be displayed regardless if the menu
manager has returned to the calling
function, 0 otherwise.
BAR_ENHANCED_ON(b) - Returns 1 if the bar menu will recognize
enhanced keys, 0 otherwise.
BAR_ENTRY_AVAILABLE(b,entry) - Returns 1 if the
BAR_MENU_ENTRY entry is
available, 0 otherwise.
BAR_ENTRY_STRING(b,entry) - Returns the entry string of
BAR_MENU_ENTRY entry.
BAR_EXPLODE(b) - Returns the special effect constant of the
BAR_MENU_PTR b. This special effect is
used to hide, close, and open the popup
menu's window.
BAR_NUMBER_OF_ENTRIES(b) - Returns the total number of
entries defined in the
BAR_MENU_PTR b.
BAR_OVERRIDE_ON(b) - Returns 1 if BAR_MENU_PTR b will have
unavailable options processed, 0
otherwise.
BAR_PULLDOWN_ON(b) - Returns 1 if the BAR_MENU_PTR b is
incorporated in a pulldown menu system,
0 otherwise.
BAR_STATIC_ON(b) - Returns 1 if the BAR_MENU_PTR b will
remain on the screen when an entry is
selected, 0 otherwise.
BAR_WINDOW(b) - Returns the WPOINTER of the bar menu.
BAR_WRAP_ON(b) - Returns 1 if the highlight wrap of
BAR_MENU_PTR b is on, otherwise 0.
Page 320 The C Window Library Page 320
Pulldown Menu Macros
--------------------
BAR_MENU_PTR_FROM_POPUP(pop) - Returns the BAR_MENU_PTR
associated with the
POPUP_MENU_PTR pop, which must
be part of a pulldown menu
system.
BAR_MENU_PTR_FROM_PULLDOWN(pull) - Returns the BAR_MENU_PTR
assocated with the
PULLDOWN_MENU_PTR pull.
POPUP_MENU_PTR_FROM_BAR(b,entry) - Returns the POPUP_MENU_PTR
associated with the BAR_MENU_PTR b. The
entry argument is the number of the
POPUP_MENU_PTR desired in the pulldown
menu system. For example, if you want to
know the first POPUP_MENU_PTR given only
a BAR_MENU_PTR, the call to this macro
would be POPUP_MENU_PTR_FROM_BAR(b,1).
POPUP_MENU_PTR_FROM_PULLDOWN(pull,entry) - Returns the
POPUP_MENU_PTR associated with the
PULLDOWN_MENU_PTR pull. The entry is the
number of the desired POPUP_MENU_PTR
desired in the pulldown menu system.
PULLDOWN_MENU_PTR_FROM_BAR(b) - Returns the PULLDOWN_MENU_PTR
associated with the bar menu
b.
PULLDOWN_MENU_PTR_FROM_POPUP(pop) - Returns the
PULLDOWN_MENU_PTR
associated with the
POPUP_MENU_PTR pop.
Page 321 The C Window Library Page 321
VIDEO MACROS
------------
The following macros are defined in the vidsys.h file. Note:
by including window.h in your source files, vidsys.h is
automatically included.
CHECK_SNOW - Returns 1 if during direct screen writes that
video "snow" is eliminated. You can also assign
values to this macro. This macro is a pseudonym
for the variable chksnow_.
Example:
#include "vidsys.h"
...
int a;
a = CHECK_SNOW; /* Returns 1 if snow checking
on,
0 otherwise */
CHECK_SNOW = 0; /* Turn off snow checking */
CREATE_VIDEO_ATTRIBUTE(bg,fg) - creates a video attribute
using bg as the background color, and fg as
the foreground color. The following
variables can be used:
Variable
Name Color Value
------- ----- -----
black Black 0
blue Blue 1
green Green 2
cyan Cyan 3
red Red 4
magenta Magenta 5
brown Brown 6
white White 7
gray Gray 8
lightblue Light Blue 9
lightgreen Light green 10
lightcyan Light cyan 11
lightred Light red 12
lightmagenta Light magenta 13
yellow Yellow 14
lightwhite Intense white 15
The variables above are initialized when
WindowInitializeSystem() is called. If you want to use a
color value before WindowInitializeSystem() is called, you
can use the uppercase equivalent of the above variables, with
Page 322 The C Window Library Page 322
a trailing underscore character attached to the name. For
example BLACK_ would be used instead of black, WHITE_ would
be used instead of white, etc. For monochrome systems, the
only colors that are available are black, white, and intense
white. An attribute of blue creates an underline attribute,
and light blue creates an intense underlined attribute. Any
other combination on a monochrome system is undefined.
GET_BGROUND_COLOR(c) - Returns the background color of the
video attribute c.
GET_FGROUND_COLOR(c) - Returns the foreground color of the
video attribute c.
GET_OFFSET(x) - Returns the offset of a pointer x. The
pointer can be either near or far.
GET_SEGMENT(x) - Returns the segment address of a pointer x.
The pointer can be either near or far.
MAKE_FAR_POINTER(a,b) - Creates a far pointer made up of
segment address a, and offset address
b.
SCREEN_OFFSET(r,c,a) - Returns the screen offset of the
address of a character located at row
r and column c of the video page a.
The screen segment is defined in the
macro SCREEN_SEGMENT. both r and c
should be >= 1.
Example: char far *p;
p = MAKE_FAR_POINTER(SCREEN_SEGMENT,SCREEN_OFFSET(1,1,0));
The above example has created a far pointer p that points
to the screen buffer memory at row 1, column 1, on video
page 0.
SCREEN_OFFSET_ATTR(r,c,a) - Returns the screen offset of the
address of a attribute located at row r
and column c of the video page a. The
screen segment is defined in the macro
SCREEN_SEGMENT. both r and c should be
>= 1.
SCREEN_SEGMENT - Returns the screen segment of video page 0.
This macro is a pseudonym for the variable
scrnseg_.
SCREEN_WRITE_METHOD - Returns 1 if writing directly to the
screen, 0 if using the BIOS. You can
also use this macro to assign the
particular writing method. This macro
Page 323 The C Window Library Page 323
controls the way The C Window Library
will do screen updates. The default is
1 (write directly to screen).
Example:
#include "vidsys.h"
int a,b;
a = SCREEN_WRITE_METHOD;
SCREEN_WRITE_METHOD = 1;
This macro is a pseudonym for the variable scrnwrt_flag
which is a member of the SYS_FLAGS structure
video_system_flags.
VIDEO_PAGESIZE - Returns the size (in bytes) of a video page.
You can also assign values to
VIDEO_PAGESIZE, but the best thing to do is
to leave it alone unless you are familiar
with the video system you are using. This
macro is a pseudonym for the variable
pagesize_.
Example:
#include "vidsys.h"
int psize;
psize = VIDEO_PAGESIZE; /* Return the current
video page size */
The following macros are used to identify the monitor type
and video card being used in the system. Note : These
macros are pseudonyms for members in the SYS_FLAGS structure
called video_system_flags.
CGA_ACTIVE - Returns 1 if Color Graphics Adapter is
active, 0 otherwise.
EGA_ACTIVE - Returns 1 if EGA is active, 0 otherwise.
EGA_COLOR_ATTACHED - Returns 1 if monitor hooked up to EGA
is a high resolution color monitor, 0
otherwise.
EGA_COLOR_ON - Returns 1 if EGA is in color mode, 0
otherwise.
EGA_INSTALLED - Returns 1 if EGA is installed, 0 otherwise.
HERCULES_ACTIVE - Returns 1 if Hercules adapter is active, 0
otherwise.
MCGA_ACTIVE - Returns 1 if the MCGA is the active video
card.
Page 324 The C Window Library Page 324
MCGA_COLOR_ON - Returns 1 if MCGA is in color mode, 0
otherwise.
MCGA_INSTALLED - Returns 1 if MCGA is installed (IBM PS/2
Model 30), 0 otherwise.
MDA_ACTIVE - Returns 1 if MDA (Monochrome) adapter is
active, 0 otherwise.
MONO_MODE_ON - Returns 1 if Monochrome mode is on
regardless of the adapter, 0 otherwise.
VGA_ACTIVE - Returns 1 if VGA is active adapter, 0
otherwise.
VGA_COLOR_ATTACHED - Returns 1 if monitor hooked up to VGA
is analog color, 0 otherwise.
VGA_COLOR_ON - Returns 1 if VGA is in color mode, 0
otherwise.
VGA_INSTALLED - Returns 1 if VGA Adapter is installed, 0
otherwise.
You should always check the ..._ACTIVE constants before
checking for other aspects of the video system. For
example, make sure that VGA_ACTIVE returns 1 before checking
any other VGA_... macro. If VGA_ACTIVE is 1, then all
VGA_... macros are valid. The same thing goes for EGA.
MONO_MODE_ON is the only macro that can be tested regardless
of the video adapter.
The following are macros defined in version 1.0 of The C
Window Library, which are still supported:
CGA_MODE_ON - Same as CGA_ACTIVE.
EGA_MODE_ON - Same as EGA_ACTIVE.
VGA_MODE_ON - Same as VGA_ACTIVE.
MCGA_MODE_ON - Same as MCGA_ACTIVE.
EGA_MONO_ON - Returns 1 if EGA is in mono mode.
VGA_MONO_ON - Returns 1 if VGA is in mono mode.
MCGA_MONO_ON - Returns 1 if MCGA is in mono mode.
You should not assign values to the above pseudo-constants
unless you are completely familiar with The C Window
Library's internal functions.
LINEMODE25 - Returns 1 if screen displays 25 lines, 0
otherwise.
LINEMODE43 - Returns 1 if screen displays 43
lines (EGA and VGA), 0 otherwise.
LINEMODE50 - Returns 1 if screen displays 50 lines (VGA), 0
otherwise.
Page 325 The C Window Library Page 325
BOX MACROS
----------
The list of defined box drawing macros is as follows:
DOUBLEBOX
SINGLEBOX
MIXEDBOX1
MIXEDBOX2
HATCHBOX1
HATCHBOX2
HATCHBOX3
SOLIDBOX1
SOLIDBOX2
BLANKBOX
DOTTEDLINE
Each one of these macros are 8 character strings that can be
used in functions that call for a string of box drawing
characters.
Page 326 The C Window Library Page 326
EXPLOSION MACROS
----------------
The list of explosion constants is as follows:
NOEFFECT
EXPLODE
CONTRACT
BRICKS
MIDDLEROWOUT
TOPBOTTOMIN
TOPDOWN
BOTTOMUP
MIDDLECOLOUT
LEFTRIGHTIN
LEFTTORIGHT
RIGHTTOLEFT
Page 327 The C Window Library Page 327
KEYBOARD MACROS
---------------
The following macros are used to get characters from the
keyboard. They are prototyped in the file key.h.
ENHANCED_KEYBOARD() - Returns 1 if there is an enhanced
keyboard attached, 0 otherwise.
FLUSH_KEYBOARD() - Flushes the keyboard buffer.
GET_KEY() - Returns what key was pressed either as a
character, or as a scan code if a non-ascii key
is pressed. A list of scan codes are found in
the file keycodes.h.
GET_ENHANCED_KEY() - Same as GET_KEY() except that keys on
the enhanced keyboards are
distinguishable. For instance, the key
on the keypad will return a different
scan code than the Home key on the
separate cursor movement pad.
GET_SHIFT_STATE() - Returns the shift state of the keyboard.
The shift state tells whether the Alt,
Ctrl or Shift key was pressed, or if the
Num Lock, Scroll Lock, or Caps Lock keys
are on or off. The shift state is
updated after each call to GET_KEY() or
GET_ENHANCED_KEY(). Use a bitwise AND
(&) when testing for these keys.
The #defined constants that are used to
test for the various keys is found in
keycodes.h.
Example:
#include "key.h"
#include "keycodes.h"
#include <stdio.h>
main()
{
int CurrentShift;
GET_KEY();
/* both ALT and CTRL must be pressed */
CurrentShift = (GET_SHIFT_STATE() & ALT) &&
(GET_SHIFT_STATE() & CTRL);
printf("The Ctrl and Alt key was %s pressed",
CurrentShift?"":"not");
}
Page 328 The C Window Library Page 328
ISKEYREADY() - Returns 1 if there is a key ready in the
keyboard buffer, 0 otherwise.
Keyboard Idle function
----------------------
When calling the GET_KEY() or GET_ENHANCED_KEY() macros, you
can call a function while the program is waiting for a key to
be pressed. The global variable key_idle_func is a function
pointer that points to this function. Here is the prototype:
void (*key_idle_func)(void)
There are no arguments and no return value to this function.
You must initialize this function pointer after you have
called WindowInitializeSystem(). If not, the function you
assigned will not be executed. Here is an example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
void count_numbers(void);
int num = 0;
main()
{
WindowInitializeSystem();
key_idle_func = count_numbers;
ClearScreen(NORM);
GET_KEY();
MoveCursor(2,1,0);
VideoPrintf("You stopped the count at %d",num);
}
void count_numbers()
{
num++;
MoveCursor(1,1,0);
VideoPrintf("%d",num);
delay(1000);
}
The program above keeps a counter going in the upper left
hand corner of the screen until a key is pressed.
If you want to unassign the key_idle_func function pointer,
do the following:
key_idle_func = VOIDNULLFN;
This function can perform just about anything. One major use
would be to update an on-screen clock while the keyboard is
not being used.
Page 329 The C Window Library Page 329
Keyboard Intercept function
---------------------------
Before GET_KEY() and GET_ENHANCED_KEY() return a value, you
can intercept the pending return value, examine it, and
change the value to whatever you wish. This is good if you
want to reassign keys easily. The function pointer to assign
is key_intercept_func. Here is the prototype:
unsigned (*key_intercept_func)(int which, unsigned keyval)
The first argument is an integer that denotes whether a mouse
button was pressed, or a key from the keyboard was pressed.
If a keyboard key was pressed, the value of which is equal to
KEYPRESSED, otherwise it is MOUSEPRESSED. If you do not have
a mouse, or the mouse is not activated, this value will
always be KEYPRESSED. More information on the mouse in the
USING THE MOUSE section in the manual. The return value will
be the new key value that GET_KEY() and GET_ENHANCED_KEY()
will return. It is advisable to use the key codes described
in "keycodes.h" if you are returning a non-ascii key. Here
is an example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
unsigned switch_to_quotes(int,unsigned);
unsigned oldchar;
main()
{
int ch;
WindowInitializeSystem();
key_intercept_func = switch_to_quotes;
ClearScreen(NORM);
ch = GET_KEY();
MoveCursor(1,1,0);
VideoPrintf(
"The old key was %c. The new code is %c",oldchar,ch);
}
unsigned switch_to_quotes(int which, unsigned keyval)
{
if (which == KEYPRESSED)
{
oldchar = keyval;
return (unsigned)'"'; /* return a double quote */
}
}
Page 330 The C Window Library Page 330
The program above intercepts the return value of GET_KEY()
and assigns the double quote character. The character is
then printed out on the screen along with the character that
was assigned.
If you want to unassign the key_intercept_func function
pointer, do the following:
key_intercept_func = NULLFN;
Checking for mouse button presses
---------------------------------
The GET_MPRESS_KEY() and GET_MPRESS_ENHANCED_KEY() macros
work the same as the GET_KEY() and GET_ENHANCED_KEY()
macros, which are described below and used in some previous
examples, except that GET_MPRESS_KEY() and
GET_MPRESS_ENHANCED_KEY() also test to see if one or more
mouse buttons has been pressed.
When GET_MPRESS_KEY() or GET_MPRESS_ENHANCED_KEY() is
called, the program is suspended until a key on the keyboard
is pressed, or one or more mouse buttons has been pressed.
The difference between these two macros is that
GET_MPRESS_ENHANCED_KEY() recognizes keys on an enhanced
(101 key) keyboard. Here is a prototype for both of these
macros:
unsigned int GET_MPRESS_KEY(int *which)
unsigned int GET_MPRESS_ENHANCED_KEY(int *which)
The only argument is a pointer to an integer which will
contain either MOUSEPRESSED if the mouse was pressed, or
KEYBOARDPRESSED if a key on the keyboard was pressed. The
kyboard_idle_func and keyboard_intercept_func function
pointers are fully implemented when either of these macros
are called.
Both of these macros return either the key that was struck,
or the mouse button(s) that was(were) pressed. The values
for these mouse buttons are as follows:
MOUSELEFT_PRESS - Left button was pressed.
MOUSERIGHT_PRESS - Right button was pressed.
MOUSEMIDDLE_PRESS - Middle button was pressed.
MOUSELEFTRIGHT_PRESS - Left and Right was pressed
simultaneously.
Page 331 The C Window Library Page 331
MOUSEMIDDLERIGHT_PRESS - Middle and Right buttons were
pressed simultaneously.
MOUSEMIDDLELEFT_PRESS - Middle and Left buttons pressed
simultaneously.
MOUSEMIDDLERIGHTLEFT_PRESS - Middle, right, and left buttons
pressed simultaneously.
If a keyboard key is hit, the return values are the same as
for GET_KEY() or GET_ENHANCED_KEY().
Example:
#include "cwlmouse.h"
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
void print_nums();
main()
{
int w,b;
unsigned ch;
WindowInitializeSystem();
ClearScreen(NORM);
MouseInitializeSystem(MOUSE_FULL_INSTALL,&b,10,10);
key_idle_func = print_nums;
ch = GET_MPRESS_KEY(&w);
VideoPrintf("\nThe %s was pressed. Value is %d",
(w==MOUSEPRESSED?"Mouse":"Keyboard"),ch);
MouseRestoreSystem();
}
void print_nums()
{
static int count = 0;
MoveCursor(1,1,0);
VideoPrintf("%d",count++);
}
Page 332 The C Window Library Page 332
CURSOR MACROS
-------------
The following macros are used for cursor manipulation.
CREATE_CURSOR_SHAPE(startline, endline) - Forms an integer
quantity representing a cursor with a
starting scan line of scanline, and an
ending scan line of endline.
THIN - constant for a thin (underline) cursor.
BLOCK - constant for a block (fat) cursor.
INVISIBLE - constant for a hidden cursor.
Page 333 The C Window Library Page 333
IMPORTANT GLOBAL VARIABLES
--------------------------
There are global variables that you should be aware of in The
C Window Library. Most of these variables can be changed,
while others should be left alone. You must call
WindowInitializeSystem() before modifying any of these
variables.
When describing the global variable, the following scheme is
used:
Variable variable name
Defined in XXXXXX.h (file where variable is declared)
Initialized in function call (function where variable gets
its initial value)
Purpose Description of variable's purpose.
Default Value default value for variable.
Modify Info Tells if variable should be modified.
These variables are described in alphabetical order.
Variable int active_video_page
Defined in vidsys.h
Initialized in WindowInitializeSystem()
Purpose Current active video page.
Modify Info Should be modified only by calling the
SetActiveVideoPage() function.
Page 334 The C Window Library Page 334
Variable int barmenu_button_press
Defined in cwlmouse.h
Initialized in MouseInitializeSystem()
Purpose Holds the current button mouse button to
press to move the highlight bar on bar
menus.
Default Value MOUSELEFT_PRESS.
Modify Info Can be modified at any time.
Variable int caldelay_
Defined vidsys.h
Initialized in WindowInitializeSystem()
Purpose This is a calibration count for the delay()
function.
Modify Info Should only be modified if the delay()
function is giving inaccurate delay times.
If the delay is too long, then caldelay_
should be decreased. If it is too short,
then caldelay_ should be increased.
Variable int check_existence_flag
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Informs The C Window Library to check for
window, virtual window, and for non-open
window errors. If this variable is 1, the
library routines will check for these
conditions. If 0, these conditions are not
checked.
Default Value 1.
Modify Info Can be modified at any time, but is
recommended that this flag be left on for
development work. Make sure that your
application program is stable if you plan to
turn off checking.
Page 335 The C Window Library Page 335
Variable int chksnow_
Defined vidsys.h
Initialized in WindowInitializeSystem()
Purpose This variable controls whether the display
should be checked for snow when writing
directly to the screen. A value of 1 will
check for snow, while a value of 0 will turn
off snow checking.
Default Value 0 (no snow checking).
Modify Info Can be modified at any time.
Variable int crt_status_port
Defined vidsys.h
Initialized in WindowInitializeSystem()
Purpose This variable holds the value of the CRT
status port. This port is used to test when
it is safe to read or write characters to
the screen without producing snow.
Modify Info Should not be modified.
Variable int default_cursor_mode
Defined key.h
Initialized in WindowInitializeSystem()
Purpose Holds the mode that the WindowGet...()
functions will operate in when called. The
modes are either OVERSTRIKEMODE or
INSERTMODE.
Default Value OVERSTRIKEMODE.
Modify Info Can be modified at any time.
Example:
default_cursor_mode = INSERTMODE;
Page 336 The C Window Library Page 336
Variable int default_cursor_type[2]
Defined key.h
Initialized in WindowInitializeSystem()
Purpose Holds the cursor shapes for OVERSTRIKEMODE
and INSERTMODE input modes.
Default Value default_cursor_type[OVERSTRIKEMODE] is set
to a block cursor.
default_cursor_type[INSERTMODE] is set to an
underline cursor.
Modify Info Can be modified at any time.
Example:
default_cursor_type[INSERTMODE] =
CREATE_CURSOR_SHAPE(5,7);
Variable int default_screen_attr
Defined in vidsys.h
Initialized in WindowInitializeSystem()
Purpose Default video attribute used when any
Video...() functions are called to write to
the screen.
Default Value 7 (black background, white foreground).
Modify Info Can be modified at any time.
Variable int enhanced_keyboard
Defined in key.h
Initialized in WindowInitializeSystem()
Purpose Tells if an enhanced keyboard is attached.
If enhanced_keyboard is 1, an enhanced
keyboard is active, otherwise if 0, the
keyboard is not an enhanced keyboard.
Modify Info Can be modified safely.
Page 337 The C Window Library Page 337
Variable int explosion_speed[12]
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose This array holds the number of milliseconds
of delay for each of the special effects
supported in The C Window Library.
Default Value 10 (10 ms.), except for
explosion_speed[BRICKS], which is 1 ms.
Modify Info Can be modified safely at anytime. The way
you would modify the values is to use the
special effects constants. For example:
explosion_speed[CONTRACT] = 5;
The above example changes the explosion
delay for the CONTRACT special effect to 5
ms.
Variable int flush_keyboard_flag.
Defined in key.h
Initialized in WindowInitializeSystem().
Purpose Tells if the keyboard buffer should be
flushed whenever the GET_KEY() or
GET_ENHANCED_KEY() macros are called. A
value of 1 means the buffer will be flushed.
Default Value 0 (no flush).
Modify Info Can be modified at any time.
Page 338 The C Window Library Page 338
Variable VIDEO_CONFIG initial_video_startup
Defined in vidsys.h
Initialized in WindowInitializeSystem()
Purpose Structure that holds the video configuration
when WindowInitializeSystem() is called.
Modify info Should not be modified if the initial video
startup is desired when exiting an
application.
Variable char input_mask_char
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Holds the mask character that is used for
input routines. The character defined in
input_mask_char is used in input masks to
specify an input position in the edit field.
Refer to the functions WindowGet..()
functions for more information concerning
character masks.
Default Value '_' (0x5F).
Modify Info Can be modified safely at any time, except
when in the middle of a user defined
function that was called by The C Window
Library's input routines.
Variable void (*key_idle_func)(void)
Defined in key.h
Initialized in WindowInitializeSystem()
Purpose pointer that points to a function that is
performed whenever the GET_KEY() and
GET_ENHANCED_KEY() macros do not have a key
ready to be processed.
Modify Info Can be modified at any time.
Page 339 The C Window Library Page 339
Variable unsigned (*key_intercept_func)(int which,
unsigned keyval)
Defined in key.h
Initialized in WindowInitializeSystem()
Purpose pointer that points to a function which
traps any keystrokes that the GET_KEY() and
GET_ENHANCED_KEY() macros will return.
Modify Info Can be modified at any time.
Variable int max_video_pages
Defined in vidsys.h
Initialized in WindowInitializeSystem()
Purpose Total number of video pages detected by The
C Window Library.
Modify Info Should not be modified unless a modification
to the screen_page_offset array was done.
Variable int max_window_rank
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Holds the rank value of the bottom-most
(i.e. the window that will have all other
windows covering it).
Modify Info Do not modify.
Page 340 The C Window Library Page 340
Variable int min_window_rank
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Holds the rank value of the top-most visible
window.
Modify Info Do not modify.
Variable int (*num_chars_entered_func)(char *string,
int minchars)
Defined in key.h
Arguments string - string that was entered.
minchars - minimum number of characters
expected.
Initialized in WindowInitializeSystem()
Purpose Pointer to user-defined function that will
be executed when the input manager detects
that there were not enough characters
entered.
Default Value NULLFN.
Variable int num_transparent_shadows[16]
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Array of the number of transparent shadows
that are currently displayed for each
display page.
Default Value 0 for each array element.
Modify Info Do not modify.
Page 341 The C Window Library Page 341
Variable WPOINTER orig_screen[16]
Defined in window.h
Initialized in WindowSaveInitial()
Purpose Array of windows created when
WindowSaveInitial() is called. The original
screen for video page 0 is orig_screen[0],
page 1 is orig_screen[1], etc. Modify Info
You can use any window function on the
original screen, except for ones that
resize, move, hide, display, or close. If
you write strings to the original screen,
you will permanently destroy the contents of
the original screen at the positions that
have been modified.
Example:
WindowWriteString(orig_screen[0],"123",1,1);
The above example writes "123" to the upper
left hand corner of the original screen of
video page 0.
Variable int pagesize_
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Holds the size of a display page in bytes.
Modify Info Should not be modified unless The C Window
Library did not detect the correct video
page size.
Page 342 The C Window Library Page 342
Variable int popmenu_button_press
Defined in cwlmouse.h
Initialized in MouseInitializeSystem()
Purpose Holds the current button mouse button to
press to move the highlight bar on popup
menus.
Default Value MOUSELEFT_PRESS.
Modify Info Can be modified at any time.
Variable int (*reg_exp_error_func)(char *string,
int nomatch)
Defined in key.h
Arguments string - string that was entered.
nomatch - position of the first non-matching
character.
Initialized in WindowInitializeSystem()
Purpose Pointer to user-defined function that will
be executed when the input manager detects
that there are illegal characters in the
string when it is compared to the regular
expression. This function is only called
when it is not equal to NULLFN, and the
CHECKREGEXP option is on.
Default Value NULLFN.
Modify info Can be modified at any time.
Return Values Must return DONT_PROCESS or ACCEPT_INPUT.
Variable unsigned char *screen_image[16]
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Used for internal window management. Each
Page 343 The C Window Library Page 343
pointer in the screen_image array points to
an image of the current window organization
of the screen. For example screen_image[0]
is a pointer to the current window "layout"
for video page 0.
Modify Info DO NOT modify this. This array is VERY
important when window updates are done.
Variable unsigned char far *screen_page_offset[16]
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Array of starting addresses of each video
page.
Modify Info You can modify if The C Window Library fails
to detect video pages that your video card
may have.
Invalid video pages will set
screen_page_offset[page] to a far NULL
pointer, where page is the invalid video
page.
If there is a failure to detect video pages
that your card may have, you can use the
MAKE_FAR_POINTER macro to initialize.
Example: screen_page_offset[page] =
MAKE_FAR_POINTER(0xB000,0x2000);
where page is the page to initialize. You
should have the documentation of the video
card on hand so that you are sure of the
starting address of the video page.
You must also adjust the global variable
max_video_pages to reflect the new number of
pages, and the pagesize_ variable to reflect
the size of each video page.
Page 344 The C Window Library Page 344
Variable int (*undef_akey_func)(char *string,
unsigned key,
int pos, int *newpos)
Defined in key.h
Arguments string - string currently entered.
key - key that was hit.
pos - position where cursor is in the input
string.
Purpose Pointer to a function that is executed when
a key that is not defined in an input
routines regular expression is pressed.
Default Value NULLFN.
Modify Info Can be modified at any time.
Return Values Refer to the manual for more information.
Variable int (*undef_fkey_func)(char *string,
unsigned key,
int pos, int *newpos)
Defined in key.h
Arguments string - string currently entered.
key - key that was hit.
pos - position where cursor is in the input
string.
Purpose Pointer to a function that is executed when
a key that is not defined in an input
routines regular expression is pressed.
Purpose Pointer to a function that is executed when
a key that is not defined in the
window_edit_key array is pressed.
Default Value NULLFN.
Modify Info Can be modified at any time.
Return Values Refer to to the main documentation for more
information.
Page 345 The C Window Library Page 345
Variable VWPOINTER virtual_window_ptrs[256]
Defined in window.h
Purpose Array of all initialized virtual window
pointers.
Modify Info Do not modify.
Variable int visible_video_page
Defined in vidsys.h
Initialized in WindowInitializeSystem()
Purpose Current visible video page.
Modify Info Should be modified only by calling the
SetVisibleVideoPage() function.
Variable unsigned window_edit_key[12]
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Array of edit key definitions. This array
is used in the window input routines.
Modify Info You can modify values in the array, provided
that there are no duplicate definitions, and
there is a definition for a key that
terminates user input. Refer to the GETTING
INPUT FROM WINDOWS section.
Page 346 The C Window Library Page 346
Variable int window_error_code
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Holds the last error that occurred as an
integer. You should always check the value
of window_error_code to determine what has
happened if a function fails. All of the
window and virtual window functions return
an error status when things go wrong.
However, only selected functions from the
Video... family of functions set
window_error_code. The value in
window_error_code corresponds to the values
found in the file werror.h.
window_error_code does not reset itself if
there are no errors.
Default Value 0.
Modify Info Safe to modify, but will always reset itself
to an error condition if a function fails.
Variable WPOINTER window_ptrs[256];
Defined in window.h
Purpose Array of all initialized windows.
Modify Info DO NOT modify.
Variable WPOINTER window_rank[257];
Defined in window.h
Purpose Array of all visible windows in rank order.
Modify Info DO NOT modify.
Page 347 The C Window Library Page 347